1.\" Copyright (c) 1980, 1991 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)open.2 6.7 (Berkeley) 05/27/91 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 <sys/file.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 105file descriptor. It 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 109The new descriptor is set to remain open across 110.Xr execve 111system calls; see 112.Xr close 2 113and 114.Xr fcntl 2 . 115.Pp 116The system imposes a limit on the number of file descriptors 117open simultaneously by one process. 118.Xr Getdtablesize 2 119returns the current system limit. 120.Sh ERRORS 121The named file is opened unless: 122.Bl -tag -width Er 123.It Bq Er ENOTDIR 124A component of the path prefix is not a directory. 125.It Bq Er ENAMETOOLONG 126A component of a pathname exceeded 255 characters, 127or an entire path name exceeded 1023 characters. 128.It Bq Er ENOENT 129.Dv O_CREAT 130is not set and the named file does not exist. 131.It Bq Er ENOENT 132A component of the path name that must exist does not exist. 133.It Bq Er EACCES 134Search permission is denied for a component of the path prefix. 135.It Bq Er EACCES 136The required permissions (for reading and/or writing) 137are denied for the given flags. 138.It Bq Er EACCES 139.Dv O_CREAT 140is specified, 141the file does not exist, 142and the directory in which it is to be created 143does not permit writing. 144.It Bq Er ELOOP 145Too many symbolic links were encountered in translating the pathname. 146.It Bq Er EISDIR 147The named file is a directory, and the arguments specify 148it is to be opened for writing. 149.It Bq Er EROFS 150The named file resides on a read-only file system, 151and the file is to be modified. 152.It Bq Er EMFILE 153The process has already reached its limit for open file descriptors. 154.It Bq Er ENFILE 155The system file table is full. 156.It Bq Er ENXIO 157The named file is a character special or block 158special file, and the device associated with this special file 159does not exist. 160.It Bq Er EINTR 161The 162.Nm 163operation was interrupted by a signal. 164.It Bq Er EOPNOTSUPP 165.Dv O_SHLOCK 166or 167.Dv O_EXLOCK 168is specified but the underlying filesystem does not support locking. 169.It Bq Er ENOSPC 170.Dv O_CREAT 171is specified, 172the file does not exist, 173and the directory in which the entry for the new file is being placed 174cannot be extended because there is no space left on the file 175system containing the directory. 176.It Bq Er ENOSPC 177.Dv O_CREAT 178is specified, 179the file does not exist, 180and there are no free inodes on the file system on which the 181file is being created. 182.It Bq Er EDQUOT 183.Dv O_CREAT 184is specified, 185the file does not exist, 186and the directory in which the entry for the new file 187is being placed cannot be extended because the 188user's quota of disk blocks on the file system 189containing the directory has been exhausted. 190.It Bq Er EDQUOT 191.Dv O_CREAT 192is specified, 193the file does not exist, 194and the user's quota of inodes on the file system on 195which the file is being created has been exhausted. 196.It Bq Er EIO 197An I/O error occurred while making the directory entry or 198allocating the inode for 199.Dv O_CREAT . 200.It Bq Er ETXTBSY 201The file is a pure procedure (shared text) file that is being 202executed and the 203.Fn open 204call requests write access. 205.It Bq Er EFAULT 206.Fa Path 207points outside the process's allocated address space. 208.It Bq Er EEXIST 209.Dv O_CREAT 210and 211.Dv O_EXCL 212were specified and the file exists. 213.It Bq Er EOPNOTSUPP 214An attempt was made to open a socket (not currently implemented). 215.El 216.Sh SEE ALSO 217.Xr chmod 2 , 218.Xr close 2 , 219.Xr dup 2 , 220.Xr getdtablesize 2 , 221.Xr lseek 2 , 222.Xr read 2 , 223.Xr write 2 , 224.Xr umask 2 225.Sh HISTORY 226An 227.Nm 228function call appeared in Version 6 AT&T UNIX. 229