1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)open.2 8.1 (Berkeley) 06/04/93 7.\" 8.Dd 9.Dt OPEN 2 10.Os BSD 4 11.Sh NAME 12.Nm open 13.Nd open or create a file for reading or writing 14.Sh SYNOPSIS 15.Fd #include <fcntl.h> 16.Ft int 17.Fn open "const char *path" "int flags" "mode_t mode" 18.Sh DESCRIPTION 19The file name specified by 20.Fa path 21is opened 22for reading and/or writing as specified by the 23argument 24.Fa flags 25and the file descriptor returned to the calling process. 26The 27.Fa flags 28argument may indicate the file is to be 29created if it does not exist (by specifying the 30.Dv O_CREAT 31flag), in which case the file is created with mode 32.Fa mode 33as described in 34.Xr chmod 2 35and modified by the process' umask value (see 36.Xr umask 2 ) . 37.Pp 38The flags specified are formed by 39.Em or Ap ing 40the following values 41.Pp 42.Bd -literal -offset indent -compact 43O_RDONLY open for reading only 44O_WRONLY open for writing only 45O_RDWR open for reading and writing 46O_NONBLOCK do not block on open 47O_APPEND append on each write 48O_CREAT create file if it does not exist 49O_TRUNC truncate size to 0 50O_EXCL error if create and file exists 51O_SHLOCK atomically obtain a shared lock 52O_EXLOCK atomically obtain an exclusive lock 53.Ed 54.Pp 55Opening a file with 56.Dv O_APPEND 57set causes each write on the file 58to be appended to the end. If 59.Dv O_TRUNC 60is specified and the 61file exists, the file is truncated to zero length. 62If 63.Dv O_EXCL 64is set with 65.Dv O_CREAT 66and the file already 67exists, 68.Fn open 69returns an error. This may be used to 70implement a simple exclusive access locking mechanism. 71If 72.Dv O_EXCL 73is set and the last component of the pathname is 74a symbolic link, 75.Fn open 76will fail even if the symbolic 77link points to a non-existent name. 78If the 79.Dv O_NONBLOCK 80flag is specified and the 81.Fn open 82call would result 83in the process being blocked for some reason (e.g., waiting for 84carrier on a dialup line), 85.Fn open 86returns immediately. 87The first time the process attempts to perform I/O on the open 88file it will block (not currently implemented). 89.Pp 90When opening a file, a lock with 91.Xr flock 2 92semantics can be obtained by setting 93.Dv O_SHLOCK 94for a shared lock, or 95.Dv O_EXLOCK 96for an exclusive lock. 97If creating a file with 98.Dv O_CREAT , 99the request for the lock will never fail 100(provided that the underlying filesystem supports locking). 101.Pp 102If successful, 103.Fn open 104returns a non-negative integer, termed a file descriptor. 105It returns -1 on failure. 106The file pointer used to mark the current position within the 107file is set to the beginning of the file. 108.Pp 109When a new file is created it is given the group of the directory 110which contains it. 111.Pp 112The new descriptor is set to remain open across 113.Xr execve 114system calls; see 115.Xr close 2 116and 117.Xr fcntl 2 . 118.Pp 119The system imposes a limit on the number of file descriptors 120open simultaneously by one process. 121.Xr Getdtablesize 2 122returns the current system limit. 123.Sh ERRORS 124The named file is opened unless: 125.Bl -tag -width Er 126.It Bq Er ENOTDIR 127A component of the path prefix is not a directory. 128.It Bq Er ENAMETOOLONG 129A component of a pathname exceeded 255 characters, 130or an entire path name exceeded 1023 characters. 131.It Bq Er ENOENT 132.Dv O_CREAT 133is not set and the named file does not exist. 134.It Bq Er ENOENT 135A component of the path name that must exist does not exist. 136.It Bq Er EACCES 137Search permission is denied for a component of the path prefix. 138.It Bq Er EACCES 139The required permissions (for reading and/or writing) 140are denied for the given flags. 141.It Bq Er EACCES 142.Dv O_CREAT 143is specified, 144the file does not exist, 145and the directory in which it is to be created 146does not permit writing. 147.It Bq Er ELOOP 148Too many symbolic links were encountered in translating the pathname. 149.It Bq Er EISDIR 150The named file is a directory, and the arguments specify 151it is to be opened for writing. 152.It Bq Er EROFS 153The named file resides on a read-only file system, 154and the file is to be modified. 155.It Bq Er EMFILE 156The process has already reached its limit for open file descriptors. 157.It Bq Er ENFILE 158The system file table is full. 159.It Bq Er ENXIO 160The named file is a character special or block 161special file, and the device associated with this special file 162does not exist. 163.It Bq Er EINTR 164The 165.Nm 166operation was interrupted by a signal. 167.It Bq Er EOPNOTSUPP 168.Dv O_SHLOCK 169or 170.Dv O_EXLOCK 171is specified but the underlying filesystem does not support locking. 172.It Bq Er ENOSPC 173.Dv O_CREAT 174is specified, 175the file does not exist, 176and the directory in which the entry for the new file is being placed 177cannot be extended because there is no space left on the file 178system containing the directory. 179.It Bq Er ENOSPC 180.Dv O_CREAT 181is specified, 182the file does not exist, 183and there are no free inodes on the file system on which the 184file is being created. 185.It Bq Er EDQUOT 186.Dv O_CREAT 187is specified, 188the file does not exist, 189and the directory in which the entry for the new file 190is being placed cannot be extended because the 191user's quota of disk blocks on the file system 192containing the directory has been exhausted. 193.It Bq Er EDQUOT 194.Dv O_CREAT 195is specified, 196the file does not exist, 197and the user's quota of inodes on the file system on 198which the file is being created has been exhausted. 199.It Bq Er EIO 200An I/O error occurred while making the directory entry or 201allocating the inode for 202.Dv O_CREAT . 203.It Bq Er ETXTBSY 204The file is a pure procedure (shared text) file that is being 205executed and the 206.Fn open 207call requests write access. 208.It Bq Er EFAULT 209.Fa Path 210points outside the process's allocated address space. 211.It Bq Er EEXIST 212.Dv O_CREAT 213and 214.Dv O_EXCL 215were specified and the file exists. 216.It Bq Er EOPNOTSUPP 217An attempt was made to open a socket (not currently implemented). 218.El 219.Sh SEE ALSO 220.Xr chmod 2 , 221.Xr close 2 , 222.Xr dup 2 , 223.Xr getdtablesize 2 , 224.Xr lseek 2 , 225.Xr read 2 , 226.Xr write 2 , 227.Xr umask 2 228.Sh HISTORY 229An 230.Nm 231function call appeared in Version 6 AT&T UNIX. 232