open(2) 							System Calls Manual							   open(2)

Name
       open - open for reading or writing

Syntax
       #include <sys/types.h>
       #include <sys/stat.h>
       #include <fcntl.h>
       #include <limits.h>     /* definition of OPEN_MAX */

       open(path, flags, mode)
       char *path;
       int flags, mode;

Description
       The  system  call opens a specified file and returns a descriptor for that file.  The file pointer used to mark the current position within
       the file is set to the beginning of the file.

       The file descriptor remains open across system calls. The system call closes the file descriptor.

       A process cannot have more than OPEN_MAX file descriptors open simultaneously.

Arguments
       path   is the address of a string of ASCII characters representing a path name, terminated by a null character.	The path  name	identifies
	      the file to be opened.

       mode   is  only	used  with  the  O_CREAT flag.	The file is created with the specified mode, as described in and modified by the process's
	      umask value.  For further information, see

       flags  defines how the file is to be opened.  This argument is formed by ORing the following values:

	      O_RDONLY	  Open for reading only.

	      O_WRONLY	  Open for writing only.

	      O_RDWR	  Open for reading and writing.

	      O_NDELAY	  Do not block on open when opening a port (named pipe) with O_RDONLY or O_WRONLY:

			  If O_NDELAY is set, an for read only returns without delay.  An for write only returns an error if no process  currently
			  has the file open for reading.

			  If  O_NDELAY	is  clear,  an	for read only blocks until a process opens the file for writing.  An for write only blocks
			  until a process opens the file for reading.

	      O_NONBLOCK  POSIX definition of O_NDELAY.  See O_NDELAY for explanation of functionality.

	      O_APPEND	  Append on each write.

	      O_CREAT	  Create file if it does not exist.

	      O_TRUNC	  Truncate size to 0.

	      O_EXCL	  Error if create and file exists.

	      O_BLKINUSE  Block if file is in use.

	      O_BLKANDSET Block if file is in use; then, set in use.

	      O_FSYNC	  Do file writes synchronously.

	      O_NOCTTY	  In the POSIX environment, if this flag is set and path identifies a terminal device, the function  will  not	cause  the
			  terminal device to become the controlling terminal for the process.

	    Opening a file with O_APPEND set causes each write on the file to be appended to the end.

	    If O_TRUNC is specified and the file exists, the file is truncated to zero length.

	    If	O_EXCL	is  set  with O_CREAT and the file already exists, the returns an error.  This can be used to implement a simple exclusive
	    access locking mechanism.

	    If the O_NDELAY or O_NONBLOCK flag is specified and the open call would result in the process being blocked for some reason, the  open
	    returns  immediately.   For example, if the process were waiting for carrier on a dialup line, an open with the O_NDELAY or O_NONBLOCK
	    flag would return immediately.  The first time the process attempts to perform I/O on the open file, it blocks.

	    If the O_FSYNC flag is specified, each subsequent write (see for the file is synchronous, instead of the default asynchronous  writes.
	    Use  this  flag  to  ensure that the write is complete when the system call returns.   With asynchronous writes, the call returns when
	    data is written to the buffer cache.  There is no guarantee that the data was actually written out to the  device.	 With  synchronous
	    writes, the call returns when the data is written from the buffer cache to the device.

	    O_BLKINUSE	and  O_BLKANDSET  provide a test and set operation similar to a semaphore.  O_BLKINUSE causes the open to block if another
	    process has marked the file as in use.  The blocks in the system at a point where no references to the file are established.

	    There are two ways to mark a file as in use:

	    o	 Use the system call with the request argument set to FIOSINUSE or TIOCSINUSE.	For further information, see

	    o	 Use the O_BLKANDSET flag to

	    O_BLKANDSET caused the to block if another process has marked the file in use.   When the resumes, the file is marked in  use  by  the
	    current process.

	    If	O_NDELAY is used with either O_BLKINUSE or O_BLKANDSET, the failed if the file is in use.  The external variable is set to EWOULD-
	    BLOCK in this case.  The in use flag cannot be inherited by a child process, nor can it be replicated by the system call.  When the in
	    use  flag is cleared, all processes that are blocked for that reason resume.  The continues to block if another process marks the file
	    as in use again.

       The in use flag can be cleared in three ways:

       o   When the file descriptor marked as in use is closed

       o   When the process that set the in use flag exits

       o   When an system call is issued and FIOCINUSE or TIOCCINUSE is specified in the request argument.

Environment
   System Five
       When your program is compiled using the System V environment, and O_NDELAY is specified, subsequent reads and writes are also affected.

Return Values
       Upon successful completion, an integer value greater than -1 is returned.

Diagnostics
       The call fails under the following conditions:

       [EACCES]       The required permissions for reading, writing, or both are denied for the named flag.

       [EACCES]       Search permission is denied for a component of the path prefix.

       [EACCES]       O_CREAT is specified, the file does not exist, and the directory in which it is to be created does not permit writing.

       [EDQUOT]       O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed  cannot
		      be extended, because the user's quota of disk blocks on the file system containing the directory has been exhausted.

       [EDQUOT]       O_CREAT  is specified, the file does not exist, and the user's quota of inodes on the file system on which the file is being
		      created has been exhausted.

       [EEXIST]       O_CREAT and O_EXCL were specified and the file exists.

       [EFAULT]       The path points outside the process's allocated address space.

       [ENFILE]       The system file table is full.

       [EINVAL]       An attempt was made to open a file with the O_RDONLY and O_FSYNC flags set.

       [EIO]	      An I/O error occurred while making the directory entry or allocating the inode for O_CREAT.

       [EISDIR]       The named file is a directory, and the arguments specify it is to be opened for writing.

       [ELOOP]	      Too many symbolic links were encountered in translating the pathname.

       [EMFILE]       {OPEN_MAX} file descriptors are currently open.

       [ENAMETOOLONG] A component of a pathname exceeds 255 characters or an entire pathname exceeds 1023 characters.

       [ENOENT]       O_CREAT is not set and the named file does not exist.

       [ENOENT]       A necessary component of the path name does not exist.

       [ENOENT]       The path argument points to an empty string and the process is running in the POSIX or SYSTEM_FIVE environment.

       [ENOSPC]       O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed  cannot
		      be extended because there is no space left on the file system containing the directory.

       [ENOSPC]       O_CREAT  is  specified,  the file does not exist, and there are no free inodes on the file system on which the file is being
		      created.

       [ENOTDIR]      A component of the path prefix is not a directory.

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

       [ENXIO]	      The O_NDELAY flag is given, and the file is a communications device on which there is no carrier present.

       [ENXIO]	      O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is set and no process has the file open for reading.

       [EOPNOTSUPP]   An attempt was made to open a socket that is not set active.

       [EROFS]	      The named file resides on a read-only file system, and the file is to be modified.

       [ESTALE]       The  file  handle  given	in the argument is invalid.  The file referred to by that file handle no longer exists or has been
		      revoked.

       [ETIMEDOUT]    A connect request or remote file operation failed because the connected party did not respond after a period of time  deter-
		      mined by the communications protocol.

       [ETXTBSY]      The file is a pure procedure (shared text) file that is being executed and the call requests write access.

       [EWOULDBLOCK]  The  open  would	have blocked if the O_NDELAY was not used. The probable cause for the block is that the file was marked in
		      use.

       [EINTR]	      A signal was caught during the function.

See Also
       chmod(2), close(2), dup(2), fcntl(2), lseek(2), read(2), write(2), umask(2), tty(4)

																	   open(2)