1.\" Copyright (c) 1980, 1991 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" from: @(#)open.2 6.7 (Berkeley) 5/27/91 33.\" $Id: open.2,v 1.4 1993/12/01 18:51:26 jtc Exp $ 34.\" 35.Dd May 27, 1991 36.Dt OPEN 2 37.Os BSD 4 38.Sh NAME 39.Nm open 40.Nd open or create a file for reading or writing 41.Sh SYNOPSIS 42.Fd #include <sys/file.h> 43.Ft int 44.Fn open "const char *path" "int flags" "mode_t mode" 45.Sh DESCRIPTION 46The file name specified by 47.Fa path 48is opened 49for reading and/or writing as specified by the 50argument 51.Fa flags 52and the file descriptor returned to the calling process. 53The 54.Fa flags 55argument may indicate the file is to be 56created if it does not exist (by specifying the 57.Dv O_CREAT 58flag), in which case the file is created with mode 59.Fa mode 60as described in 61.Xr chmod 2 62and modified by the process' umask value (see 63.Xr umask 2 ) . 64.Pp 65The flags specified are formed by 66.Em or Ap ing 67the following values 68.Pp 69.Bd -literal -offset indent -compact 70O_RDONLY open for reading only 71O_WRONLY open for writing only 72O_RDWR open for reading and writing 73O_NONBLOCK do not block on open 74O_APPEND append on each write 75O_CREAT create file if it does not exist 76O_TRUNC truncate size to 0 77O_EXCL error if create and file exists 78O_SHLOCK atomically obtain a shared lock 79O_EXLOCK atomically obtain an exclusive lock 80.Ed 81.Pp 82Opening a file with 83.Dv O_APPEND 84set causes each write on the file 85to be appended to the end. If 86.Dv O_TRUNC 87is specified and the 88file exists, the file is truncated to zero length. 89If 90.Dv O_EXCL 91is set with 92.Dv O_CREAT 93and the file already 94exists, 95.Fn open 96returns an error. This may be used to 97implement a simple exclusive access locking mechanism. 98If 99.Dv O_EXCL 100is set and the last component of the pathname is 101a symbolic link, 102.Fn open 103will fail even if the symbolic 104link points to a non-existent name. 105If the 106.Dv O_NONBLOCK 107flag is specified and the 108.Fn open 109call would result 110in the process being blocked for some reason (e.g., waiting for 111carrier on a dialup line), 112.Fn open 113returns immediately. 114The first time the process attempts to perform I/O on the open 115file it will block (not currently implemented). 116.Pp 117When opening a file, a lock with 118.Xr flock 2 119semantics can be obtained by setting 120.Dv O_SHLOCK 121for a shared lock, or 122.Dv O_EXLOCK 123for an exclusive lock. 124If creating a file with 125.Dv O_CREAT , 126the request for the lock will never fail 127(provided that the underlying filesystem supports locking). 128.Pp 129If successful, 130.Fn open 131returns a non-negative integer, termed a 132file descriptor. It returns -1 on failure. 133The file pointer used to mark the current position within the 134file is set to the beginning of the file. 135.Pp 136The new descriptor is set to remain open across 137.Xr execve 138system calls; see 139.Xr close 2 140and 141.Xr fcntl 2 . 142.Pp 143The system imposes a limit on the number of file descriptors 144open simultaneously by one process. 145.Xr Getdtablesize 2 146returns the current system limit. 147.Sh ERRORS 148The named file is opened unless: 149.Bl -tag -width Er 150.It Bq Er ENOTDIR 151A component of the path prefix is not a directory. 152.It Bq Er ENAMETOOLONG 153A component of a pathname exceeded 255 characters, 154or an entire path name exceeded 1023 characters. 155.It Bq Er ENOENT 156.Dv O_CREAT 157is not set and the named file does not exist. 158.It Bq Er ENOENT 159A component of the path name that must exist does not exist. 160.It Bq Er EACCES 161Search permission is denied for a component of the path prefix. 162.It Bq Er EACCES 163The required permissions (for reading and/or writing) 164are denied for the given flags. 165.It Bq Er EACCES 166.Dv O_CREAT 167is specified, 168the file does not exist, 169and the directory in which it is to be created 170does not permit writing. 171.It Bq Er ELOOP 172Too many symbolic links were encountered in translating the pathname. 173.It Bq Er EISDIR 174The named file is a directory, and the arguments specify 175it is to be opened for writing. 176.It Bq Er EROFS 177The named file resides on a read-only file system, 178and the file is to be modified. 179.It Bq Er EMFILE 180The process has already reached its limit for open file descriptors. 181.It Bq Er ENFILE 182The system file table is full. 183.It Bq Er ENXIO 184The named file is a character special or block 185special file, and the device associated with this special file 186does not exist. 187.It Bq Er EINTR 188The 189.Fn open 190operation was interrupted by a signal. 191.It Bq Er EOPNOTSUPP 192.Dv O_SHLOCK 193or 194.Dv O_EXLOCK 195is specified but the underlying filesystem does not support locking. 196.It Bq Er ENOSPC 197.Dv O_CREAT 198is specified, 199the file does not exist, 200and the directory in which the entry for the new file is being placed 201cannot be extended because there is no space left on the file 202system containing the directory. 203.It Bq Er ENOSPC 204.Dv O_CREAT 205is specified, 206the file does not exist, 207and there are no free inodes on the file system on which the 208file is being created. 209.It Bq Er EDQUOT 210.Dv O_CREAT 211is specified, 212the file does not exist, 213and the directory in which the entry for the new file 214is being placed cannot be extended because the 215user's quota of disk blocks on the file system 216containing the directory has been exhausted. 217.It Bq Er EDQUOT 218.Dv O_CREAT 219is specified, 220the file does not exist, 221and the user's quota of inodes on the file system on 222which the file is being created has been exhausted. 223.It Bq Er EIO 224An I/O error occurred while making the directory entry or 225allocating the inode for 226.Dv O_CREAT . 227.It Bq Er ETXTBSY 228The file is a pure procedure (shared text) file that is being 229executed and the 230.Fn open 231call requests write access. 232.It Bq Er EFAULT 233.Fa Path 234points outside the process's allocated address space. 235.It Bq Er EEXIST 236.Dv O_CREAT 237and 238.Dv O_EXCL 239were specified and the file exists. 240.It Bq Er EOPNOTSUPP 241An attempt was made to open a socket (not currently implemented). 242.El 243.Sh SEE ALSO 244.Xr chmod 2 , 245.Xr close 2 , 246.Xr dup 2 , 247.Xr getdtablesize 2 , 248.Xr lseek 2 , 249.Xr read 2 , 250.Xr write 2 , 251.Xr umask 2 252.Sh HISTORY 253An 254.Fn open 255function call appeared in 256.At v6 . 257