open(2) 							System Calls Manual							   open(2)

NAME

       open, creat - Opens a file for reading or writing

SYNOPSIS

       #include <fcntl.h> #include <sys/stat.h> #include <sys/types.h>

       int open (
	       const char *path,
	       int oflag [ ,
	       mode_t mode ] );

       int creat (
	       const char *path,
	       mode_t mode );

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       creat():  POSIX.1, XPG4, XPG4-UNIX

       open():	POSIX.1, XPG4, XPG4-UNIX

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Specifies the file to be opened or created.  If the path parameter refers to a symbolic link, the open() function opens the file pointed to
       by the symbolic link.  Specifies the type of access, special open processing, the type of update, and the initial state of the  open  file.
       The  parameter  value is constructed by logically OR-ing special open processing flags.	These flags are defined in the fcntl.h header file
       and are described below.  Specifies the read, write, and execute permissions of the file to be created (requested by the  O_CREAT  flag	in
       the  open()  interface).   If  the file already exists, this parameter is ignored. This parameter is constructed by logically OR-ing values
       described in the sys/mode.h header file.

DESCRIPTION

       The following two function calls are equivalent:

       creat(path, mode);

       open(path, O_WRONLY | O_CREAT | O_TRUNC, mode);

       The open() and creat() functions establish a connection between the file named by the path parameter and a file descriptor.  Subsequent I/O
       functions, such as  read() and write(), use the open file descriptor to access the file.

       The  file  descriptor  returned	for a file is the lowest file descriptor not previously opened for that process.  In most cases, a process
       cannot have more than OPEN_MAX file descriptors open simultaneously.  The per-process soft descriptor limit is configurable.   The  minimum
       value is 64.  See getrlimit(2) and setrlimit(2).

       The open() and creat() functions suspend the calling process until the calling thread is suspended.

       When an open() or creat() function is called, the file offset, which marks the current position within the file, is set to the beginning of
       the file.  The new file descriptor is set to remain open across exec functions (see fcntl(2)).

       The file status flags and file access flags are designated by the oflag parameter.  The oflag parameter is constructed by bitwise-inclusive
       OR-ing exactly one of the file access flags with one or more of the file status flags.

   File Access Flags
       The  file  access  flags, which specify read and write access are as follows: The file is open only for reading.  The file is open only for
       writing.  The file is open for reading and writing.

       Only one file access value (O_RDONLY, O_WRONLY, or O_RDWR) can be specified.  If exactly no value is set, the default O_RDONLY is used.

   File Status Flags
       The file status flags, which specify file open processing, are as follows: If the file exists, this flag has no effect, except as described
       under  the  O_EXCL flag. If the file does not exist, a regular file is created with the following characteristics: The owner ID of the file
       is set to the effective user ID of the process.	The group ID of the file is set to the group ID of its parent directory.

	      However, when the vfs subsystem attribute sys_v_mode is set to 1, the group ID of the file is set either to  the	group  ID  of  the
	      process or, if the S_ISGID bit of the parent directory is set, to the group ID of the parent directory.

	      If  the group ID of the new file does not match the process's effective group or one of its supplementary group IDs, the S_ISGID bit
	      of the new file is cleared.

	      The access permission bits of the file mode are set to the value of mode as follows:  The corresponding bits  are  AND-ed  with  the
	      complement  of the file mode creation mask for the process.  The file permission and attribute bits are set to the value of the mode
	      parameter, which is modified as follows: All bits in the file mode whose corresponding bits in the file mode creation mask  are  set
	      are  cleared.  The set-user ID attribute (S_ISUID bit) is cleared.  The set-group ID attribute (S_ISGID bit) is cleared.	The access
	      control list of the new file is set to WILDCARD (discretionary access to the file according to traditional UNIX rules).

	      To create a new file, the calling process must have permission to write to the file's parent directory with respect  to  all  access
	      control policies.  If the file exists and O_EXCL and O_CREAT are set, the open will fail.  If the path parameter identifies a termi-
	      nal device, this flag assures that the terminal device does not become the controlling terminal for the process.

	      System V Compatibility

	      In the Tru64 UNIX operating system, O_NOCTTY is set by default and cannot be unset.  In the System V habitat, however,  O_NOCTTY	is
	      not  set	by  default, and a terminal device can become the controlling terminal for the process if both of the following conditions
	      are met: The process does not already have a controlling terminal.  The terminal device pointed to by path is not already a control-
	      ling terminal.  If the file does not exist, this flag has no effect.

	      If  the file exists, is a regular file, and is successfully opened with O_WRONLY or O_RDWR*, the following occurs: The length of the
	      file is truncated to 0 (zero).  The owner and group of the file are unchanged.  The set-user  ID	attribute  of  the  file  mode	is
	      cleared,	unless	the  vfs subsystem variable sys_v_mode is set to 1.  In this case, the file length is truncated to 0 and the mode,
	      owner, and group are not changed.  The set-user ID attribute of the file is cleared.

	      The open fails if either of the following conditions is true: The file supports enforced record locks and another process has locked
	      a portion of the file.  The file does not allow write access.

	      If the oflag parameter also specifies O_SYNC, O_DSYNC, or O_RSYNC, the truncation becomes a synchronous update.

	      A program can request some control over when updates should be made permanent for a regular file that is opened for write access.

	      The calling process must have write access to the file with respect to all access policies.

       File  status  flags that specify special processing for subsequent reads and writes of the open file are as follows: If set, and if the vfs
       subsystem variable strict_posix_osync is set to 1 (enabled), updates and writes to regular  files  and  block  devices  will  synchronously
       update  data and file attribute information.  When a function that performs an O_SYNC synchronous update (a write() system call when O_SYNC
       is set) returns, the calling process is assured that all data and file attribute information has been written to permanent storage, even if
       a  file	is  also  open	for deferred (asynchronous) update.  If the strict_posix_osync variable is set to 0, updates and writes to regular
       files and block devices synchronously update only data (see the O_DSYNC flag).  If set, updates and  writes  to	regular  files	and  block
       devices	will  synchronously  update only the data and file attributes that are required to retrieve data.  For example, this occurs when a
       file is extended.  When a function returns that performs an O_DSYNC synchronous update (a write() system call when  O_DSYNC  is	set),  the
       calling	process  is assured that all data has been written to permanent storage.  However, using O_DSYNC does not guarantee that file-con-
       trol information, such as owner and modification time, is updated to permanent storage.	If set and if O_DSYNC is set, enables synchronized
       I/O  data integrity for read operations.  The calling process is assured that all pending file data writes are written to permanent storage
       prior to a read.

	      If set, and if O_SYNC is set, enables synchronized I/O file integrity for read operations.  The calling process is assured that  all
	      data and file attribute information is written to permanent storage prior to a read.

	      If  O_RSYNC stoppp is used alone, it has no effect.  If set, the file pointer is set to the end of the file prior to each write.	If
	      set, the call to open() will not block, and subsequent read() or write() operations on the file will be nonblocking.

   AdvFS-only File Flags
       The following file access and status flags are used only with AdvFS, and are ignored by all other file systems.	Enables direct	I/O  on  a
       file.  Also enables direct I/O for all processes that have opened the file.  Note that you cannot enable direct I/O for a data logging file
       or for a file that is mmapped.  In addition, you cannot mmap a file that has direct I/O enabled.

   General Notes on oflag Parameter Flag Values
       The effect of O_CREAT is immediate.

       When opening a FIFO with O_RDONLY: If O_NDELAY or O_NONBLOCK is not set, the open() function is blocked until  another  process	opens  the
       file  for  writing.  If	the  file  is already open for writing (even by the calling process), the open() function returns immediately.	If
       O_NDELAY or O_NONBLOCK is set, the open() function returns immediately.

       When opening a FIFO with O_WRONLY: If O_NDELAY or O_NONBLOCK is not set, the open() function is blocked until  another  process	opens  the
       file  for  reading.   If the file is already open for reading (even by the calling process), the open() function returns without delay.	If
       O_NDELAY or O_NONBLOCK is set, the open() function returns an error if no process currently has the file open for reading.

       When opening a block special or character special file that supports nonblocking opens (such as from a terminal	device):  If  O_NDELAY	or
       O_NONBLOCK is not set, the open() function is blocked until the device is ready or available.  If O_NDELAY or O_NONBLOCK is set, the open()
       function returns without waiting for the device to be ready or available. Subsequent behavior of the device is device-specific.

       When opening a STREAMS file, oflag may be constructed from O_NDELAY or O_NONBLOCK OR-ed with either O_RDONLY, O_WRONLY  or  O_RDWR.   Other
       flag  values are not applicable to STREAMS devices and have no effect on them.  The value of O_NDELAY or NON_BLOCK affects the operation of
       STREAMS drivers and certain system calls. See read(2), getmsg(2), putmsg(2), and write(2).  For drivers, the implementation of O_NDELAY	or
       NON_BLOCK is device-specific.  Different STREAMS device drivers may treat this option differently.

RESTRICTIONS

       Since  a  file newly created by creat() is write_only, an fdopen() call using the r+ parameter fails if it follows a creat() call.  A solu-
       tion to this problem is to create the file using a call that adheres to the following format:

       open(path, O_RDWR | O_CREAT, 0666);

RETURN VALUES

       On successful completion, the open() and creat() functions return the file descriptor, which is a nonnegative integer.  If the open  fails,
       a value of -1 is returned and errno is set to indicate the error.

ERRORS

       If the open() or creat() function fails, errno may be set to one of the following values: One of the following occurred:  Search permission
       is denied on a component of the path prefix, the type of access specified by the oflag parameter is denied for the  named  file,  the  file
       does  not  exist  and  write  permission  is  denied for the parent directory, or O_TRUNC is specified and write permission is denied.  The
       O_TRUNC flag is set, the named file exists with enforced record locking enabled, and record locks are put on the file.  The named file is a
       block  device  file  and  the  block device is in use by a mounted file system.	The directory in which the entry for the new link is being
       placed cannot be extended, because the quota of disk blocks (or inodes that are defined for the user on	the  file  system  containing  the
       directory)  has been exhausted.	The O_CREAT and O_EXCL flags are set and the named file exists.  The path parameter is an invalid address.
       A signal was caught by the open() function.  The owner or group ID is not a value supported by this implementation, or the O_DIRECTIO  flag
       was  specified  and  the file is already opened for atomic write data logging or is mmapped.  [Tru64 UNIX] O_CREAT was requested and an I/O
       error occurred when updating the directory.  The named file is a directory and write access was requested.

	      In a System V habitat, the named file is a directory and the oflag permission is write or read/write.  Too many symbolic links  were
	      encountered in translating path.

	      The  system  limit  for open file descriptors per process has already reached the OPEN_MAX limit, or the per-process soft descriptor
	      limit has already been reached.  The length of the path string exceeds PATH_MAX or a pathname component  is  longer  than  NAME_MAX.
	      The path parameter points to a remote machine and the link to that machine is no longer active.  The system file table is full.  One
	      of the following applies: The O_CREAT flag is not set and the named file does not exist, the O_CREAT is set and the path prefix does
	      not  exist, or the path parameter points to an empty string.  The system was unable to allocate kernel memory for more file descrip-
	      tors.  The directory that would contain the new file cannot be extended, the file does not exist, and O_CREAT is requested.   Unable
	      to allocate a stream.  A component of the path prefix is not a directory.  One of the following applies:

	      The named file is a character special or block special file and the device associated with this special file does not exist.

	      The  named  file	is a multiplexed special file and the channel number is outside of the valid range, or no more channels are avail-
	      able.

	      The O_NONBLOCK flag is set, the named file is a FIFO, O_WRONLY is set, and no process has the file open for reading.

	      A STREAMS module or driver open routine failed.  The named file is a socket bound to the file system (a UNIX domain socket) and can-
	      not be opened.  The named file resides on a read-only file system and write access is required.

       For NFS file access, if the open() or creat() function fails, errno may be set to one of the following values: A server attempted to handle
       an NFS request by generating a request to another NFS server, which is not allowed.  A stale NFS file handle exists.  One of the  following
       occurred:  An open file was deleted by the server or another client, the server unmounted or unexported the remote directory, or the server
       unmounted or unexported the directory that contains an open file.  A connection time-out occurred.  For files that  are	mounted  with  the
       soft option, the server is down or there is a network problem.

RELATED INFORMATION

       Functions: chmod(2), close(2), fcntl(2), getmsg(2), lseek(2), putmsg(2), read(2), stat(2), truncate(2), umask(2), write(2), lockf(3)

       Standards: standards(5) delim off

																	   open(2)