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.6 (Berkeley) 03/10/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_NDELAY 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 51.Ed 52.Pp 53Opening a file with 54.Dv O_APPEND 55set causes each write on the file 56to be appended to the end. If 57.Dv O_TRUNC 58is specified and the 59file exists, the file is truncated to zero length. 60If 61.Dv O_EXCL 62is set with 63.Dv O_CREAT 64and the file already 65exists, 66.Fn open 67returns an error. This may be used to 68implement a simple exclusive access locking mechanism. 69If 70.Dv O_EXCL 71is set and the last component of the pathname is 72a symbolic link, 73.Fn open 74will fail even if the symbolic 75link points to a non-existent name. 76If the 77.Dv O_NDELAY 78flag is specified and the 79.Fn open 80call would result 81in the process being blocked for some reason (e.g., waiting for 82carrier on a dialup line), 83.Fn open 84returns immediately. 85The first time the process attempts to perform I/O on the open 86file it will block (not currently implemented). 87.Pp 88If successful, 89.Fn open 90returns a non-negative integer, termed a 91file descriptor. It returns -1 on failure. 92The file pointer used to mark the current position within the 93file is set to the beginning of the file. 94.Pp 95The new descriptor is set to remain open across 96.Xr execve 97system calls; see 98.Xr close 2 99and 100.Xr fcntl 2 . 101.Pp 102The system imposes a limit on the number of file descriptors 103open simultaneously by one process. 104.Xr Getdtablesize 2 105returns the current system limit. 106.Sh ERRORS 107The named file is opened unless: 108.Bl -tag -width Er 109.It Bq Er ENOTDIR 110A component of the path prefix is not a directory. 111.It Bq Er EINVAL 112The pathname contains a character with the high-order bit set. 113.It Bq Er ENAMETOOLONG 114A component of a pathname exceeded 255 characters, 115or an entire path name exceeded 1023 characters. 116.It Bq Er ENOENT 117.Dv O_CREAT 118is not set and the named file does not exist. 119.It Bq Er ENOENT 120A component of the path name that must exist does not exist. 121.It Bq Er EACCES 122Search permission is denied for a component of the path prefix. 123.It Bq Er EACCES 124The required permissions (for reading and/or writing) 125are denied for the given flags. 126.It Bq Er EACCES 127.Dv O_CREAT 128is specified, 129the file does not exist, 130and the directory in which it is to be created 131does not permit writing. 132.It Bq Er ELOOP 133Too many symbolic links were encountered in translating the pathname. 134.It Bq Er EISDIR 135The named file is a directory, and the arguments specify 136it is to be opened for writing. 137.It Bq Er EROFS 138The named file resides on a read-only file system, 139and the file is to be modified. 140.It Bq Er EMFILE 141The process has already reached its limit for open file descriptors. 142.It Bq Er ENFILE 143The system file table is full. 144.It Bq Er ENXIO 145The named file is a character special or block 146special file, and the device associated with this special file 147does not exist. 148.It Bq Er ENOSPC 149.Dv O_CREAT 150is specified, 151the file does not exist, 152and the directory in which the entry for the new file is being placed 153cannot be extended because there is no space left on the file 154system containing the directory. 155.It Bq Er ENOSPC 156.Dv O_CREAT 157is specified, 158the file does not exist, 159and there are no free inodes on the file system on which the 160file is being created. 161.It Bq Er EDQUOT 162.Dv O_CREAT 163is specified, 164the file does not exist, 165and the directory in which the entry for the new fie 166is being placed cannot be extended because the 167user's quota of disk blocks on the file system 168containing the directory has been exhausted. 169.It Bq Er EDQUOT 170.Dv O_CREAT 171is specified, 172the file does not exist, 173and the user's quota of inodes on the file system on 174which the file is being created has been exhausted. 175.It Bq Er EIO 176An I/O error occurred while making the directory entry or 177allocating the inode for 178.Dv O_CREAT . 179.It Bq Er ETXTBSY 180The file is a pure procedure (shared text) file that is being 181executed and the 182.Fn open 183call requests write access. 184.It Bq Er EFAULT 185.Fa Path 186points outside the process's allocated address space. 187.It Bq Er EEXIST 188.Dv O_CREAT 189and 190.Dv O_EXCL 191were specified and the file exists. 192.It Bq Er EOPNOTSUPP 193An attempt was made to open a socket (not currently implemented). 194.El 195.Sh SEE ALSO 196.Xr chmod 2 , 197.Xr close 2 , 198.Xr dup 2 , 199.Xr getdtablesize 2 , 200.Xr lseek 2 , 201.Xr read 2 , 202.Xr write 2 , 203.Xr umask 2 204.Sh HISTORY 205An 206.Nm 207function call appeared in Version 6 AT&T UNIX. 208