.\" SCCSID: @(#)open.2	2.1	3/10/87.TH open 2.SH Nameopen \- open for reading or writing .SH Syntax#include <sys/types.h>.br#include <sys/stat.h>.br#include <fcntl.h>.br#include <limits.h>     /* definition of OPEN_MAX */.PPopen(\fIpath, flags, mode\fP).brchar *\fIpath\fP;.brint \fIflags, mode\fP;.SH Description.NXA "open system call" "close system call".NXR "open system call".NXR "file" "opening".NXR "file" "marking in use"The.PN opensystem call opens a specified file and returns a descriptor for that file.The file pointer used to mark the current position withinthe file is set to the beginning of the file..PPThe file descriptor remains open across .PN execve system calls. The .PN close  system call closes the file descriptor..PPA process cannot have more than OPEN_MAX file descriptorsopen simultaneously.  .SH Arguments.IP \fIpath\fR 7is the address of a string of ASCII characters representinga path name, terminated by a null character.  The path nameidentifies the file to be opened..IP \fImode\fR is only used with the O_CREAT flag.  The file is createdwith the specified mode, as described in.MS chmod 2and modified by the process's umask value.For further information, see.MS umask 2 ..IP \fIflags\fR defines how the file is to be opened.  This argument is formed byORingthe following values:.NXR "open system call" "flags".RS.IP "O_RDONLY" 1.25iOpen for reading only..IP "O_WRONLY" 1.25iOpen for writing only..IP "O_RDWR" 1.25iOpen for reading and writing..IP "O_NDELAY" 1.25iDo not block on openwhen opening a port (named pipe) with O_RDONLY or O_WRONLY:.IP If O_NDELAY is set, an .PN openfor read only returns without delay.  An.PN openfor write only returns an error if no process currently hasthe file open for reading..IP If O_NDELAY is clear, an.PN openfor read only blocks until a process opens thefile for writing.  An.PN openfor write only blocks until a process opens thefile for reading..IP "O_NONBLOCK" 1.25iPOSIX definition of O_NDELAY.  See O_NDELAY for explanation of functionality..IP "O_APPEND" 1.25iAppend on each write..IP "O_CREAT" 1.25iCreate file if it does not exist..IP "O_TRUNC" 1.25iTruncate size to 0..IP "O_EXCL" 1.25iError if create and file exists..IP "O_BLKINUSE" 1.25iBlock if file is in use..IP "O_BLKANDSET" 1.25iBlock if file is in use; then, set in use..IP "O_FSYNC" 1.25iDo file writes synchronously..IP "O_NOCTTY" 1.25iIn the POSIX environment, if this flag is set and pathidentifies a terminal device, the.PN open()function will not cause the terminal device to become the controllingterminal for the process..RE.IP "" .5iOpening a file with O_APPEND set causes each write on the fileto be appended to the end.  .IP "" .5iIf O_TRUNC is specified and thefile exists, the file is truncated to zero length..IP "" .5iIf O_EXCL is set with O_CREAT and the file alreadyexists, the .PN open returns an error.  This can be used toimplement a simple exclusive access locking mechanism..IP "" .5iIf the O_NDELAY or O_NONBLOCK flag is specified and the open call would resultin the process being blocked for some reason, the open returnsimmediately.Forexample, if the process were waiting for carrier on a dialupline, 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 openfile, it blocks. .IP "" .5iIf the O_FSYNC flag is specified, each subsequent write (see.MS write 2 )for the fileis synchronous, instead of the default asynchronouswrites.   Use this flag to ensure that the writeis complete when the system call returns.   With asynchronouswrites, 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 returnswhen the data is written from the buffer cache to the device..IP "" .5iO_BLKINUSE and O_BLKANDSET provide a test and setoperation similar to a semaphore.O_BLKINUSE causes the open to block if another process hasmarked the file as in use.  The .PN openblocks in the system at a point where no references tothe file are established..IP "" .5iThere are two ways to mark a file as in use:.RS.IP \(bu 5Use the .PN ioctl (2) system call with the .I requestargument set to FIOSINUSE or TIOCSINUSE.For further information, see.MS tty 4 ..IP \(bu 5Use the O_BLKANDSET flag to.PN open (2) ..RE.IP "" .5iO_BLKANDSET caused the  .PN open to block if another process hasmarked the file in use.   When the .PN openresumes, the fileis marked in use by the current process. .IP "" .5iIf O_NDELAY is used with either O_BLKINUSE or O_BLKANDSET, the .PN open failed if the file is in use.The external variable .PN errno is set to EWOULDBLOCK in this case..NTThe in use flag cannotbe inherited by a child process, nor can it be replicated by the.PN dup system call..NEWhen the in use flag is cleared, all processes that are blockedfor that reason resume.The .PN open continues to block if another process marks the file as in useagain..PP The in use flag can be cleared in three ways:  .IP \(bu 4When the file descriptor marked as in use is closed.IP \(buWhen the process that set the in use flag exits.IP \(buWhen an.PN ioctl system call is issued and FIOCINUSE or TIOCCINUSE is specified in the.I request argument.   .SH Environment.NXR "open system call" "System V and".SS System FiveWhen your program is compiled using the System V environment, andO_NDELAY is specified, subsequent reads and writesare also affected..SH Return ValuesUpon successful completion, an integer value greater than-1 is returned..SH Diagnostics.NXR "open system call" "diagnostics"The .PN opencall fails under the following conditions:.TP 15[EACCES]The required permissions for reading, writing, or bothare denied for the named flag..TP 15[EACCES]Search permission is denied for a component of the path prefix..TP 15[EACCES]O_CREAT is specified, the file does not exist, and thedirectory in which it is to be created does not permitwriting..TP 15[EDQUOT]O_CREAT is specified, the file does not exist, andthe directory in which the entry for the new file isbeing placed cannot be extended, because the user'squota of disk blocks on the file system containingthe directory has been exhausted..TP 15[EDQUOT]O_CREAT is specified, the file does not exist,and the user's quota of inodes on the file system onwhich the file is being created has been exhausted..TP 15[EEXIST]O_CREAT and O_EXCL were specified and the file exists..TP 15[EFAULT]The.I pathpoints outside the process's allocated address space..TP 15[ENFILE]The system file table is full..TP 15[EINVAL]An attempt was made to open a file with the O_RDONLY andO_FSYNC flags set.  .TP 15[EIO]An I/O error occurred while making the directory entry or allocatingthe inode for O_CREAT..TP 15[EISDIR]The named file is a directory, and the arguments specifyit is to be opened for writing..TP 15[ELOOP]Too many symbolic links were encountered in translating the pathname..TP 15[EMFILE]{OPEN_MAX} file descriptors are currently open..TP 15[ENAMETOOLONG]A component of a pathname exceeds 255 characters or an entirepathname exceeds 1023 characters..TP 15[ENOENT]O_CREAT is not set and the named file does not exist..TP 15[ENOENT]A necessary component of the path name does not exist..TP[ENOENT]The \fIpath\fP argument points to an empty string and the processis running in the POSIX or SYSTEM_FIVE environment..TP 15[ENOSPC]O_CREAT is specified, the file does not exist,and the directory in which the entry for the new file is beingplaced cannot be extended because there is no space left on thefile system containing the directory..TP 15[ENOSPC]O_CREAT is specified, the file does not exist, and thereare no free inodes on the file system on which thefile is being created..TP 15[ENOTDIR]A component of the path prefix is not a directory..TP 15[ENXIO]The named file is a character special or blockspecial file, and the device associated with this special filedoes not exist..TP 15[ENXIO]The O_NDELAY flag is given, and the file is a communications deviceon which there is no carrier present..TP[ENXIO]O_NONBLOCK is set, the named file is a FIFO, O_WRONLY isset and no process has the file open for reading..TP 15[EOPNOTSUPP]An attempt was made to open a socket that is not set active. .TP 15[EROFS]The named file resides on a read-only file system,and the file is to be modified..TP 15[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..TP[ETIMEDOUT]A connect request or remote file operation failedbecause the connected party did not respond after a periodof time determined by the communications protocol..TP 15[ETXTBSY]The file is a pure procedure (shared text) file that is beingexecuted and the .PN opencall requests write access..TP 15[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..TP[EINTR]A signal was caught during the.PN open()function..SH See Alsochmod(2), close(2), dup(2), fcntl(2), lseek(2), read(2), write(2), umask(2), tty(4)