1.\" $OpenBSD: open.2,v 1.24 2001/09/29 15:44:22 millert Exp $ 2.\" $NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)open.2 8.2 (Berkeley) 11/16/93 36.\" 37.Dd November 16, 1993 38.Dt OPEN 2 39.Os 40.Sh NAME 41.Nm open 42.Nd open or create a file for reading or writing 43.Sh SYNOPSIS 44.Fd #include <fcntl.h> 45.Ft int 46.Fn open "const char *path" "int flags" "mode_t mode" 47.Sh DESCRIPTION 48The file name specified by 49.Fa path 50is opened 51for reading and/or writing as specified by the 52argument 53.Fa flags 54and the file descriptor returned to the calling process. 55The 56.Fa flags 57argument may indicate the file is to be 58created if it does not exist (by specifying the 59.Dv O_CREAT 60flag), in which case the file is created with mode 61.Fa mode 62as described in 63.Xr chmod 2 64and modified by the process' umask value (see 65.Xr umask 2 ) . 66.Pp 67The flags specified are formed by 68.Tn OR Ns 'ing 69the following values 70.Pp 71.Bl -tag -width O_NONBLOCK -offset indent -compact 72.It Dv O_RDONLY 73Open for reading only. 74.It Dv O_WRONLY 75Open for writing only. 76.It Dv O_RDWR 77Open for reading and writing. 78.It Dv O_NONBLOCK 79Do not block on open or for data to become available. 80.It Dv O_APPEND 81Append on each write. 82.It Dv O_CREAT 83Create file if it does not exist. 84.It Dv O_TRUNC 85Truncate size to 0. 86.It Dv O_EXCL 87Error if create and file exists. 88.It Dv O_SYNC 89Perform synchronous I/O operations. 90.It Dv O_SHLOCK 91Atomically obtain a shared lock. 92.It Dv O_EXLOCK 93Atomically obtain an exclusive lock. 94.It Dv O_NOFOLLOW 95If last path element is a symlink, don't follow it. 96.El 97.Pp 98Opening a file with 99.Dv O_APPEND 100set causes each write on the file 101to be appended to the end. 102If 103.Dv O_TRUNC 104and a writing mode are specified and the 105file exists, the file is truncated to zero length. 106If 107.Dv O_EXCL 108is set with 109.Dv O_CREAT 110and the file already 111exists, 112.Fn open 113returns an error. 114This may be used to implement a simple exclusive access locking mechanism. 115If either of 116.Dv O_EXCL 117or 118.Dv O_NOFOLLOW 119are set and the last component of the pathname is 120a symbolic link, 121.Fn open 122will fail even if the symbolic 123link points to a non-existent name. 124If the 125.Dv O_NONBLOCK 126flag is specified, do not wait for the device or file to be ready or 127available. 128If the 129.Fn open 130call would result 131in the process being blocked for some reason (e.g., waiting for 132carrier on a dialup line), 133.Fn open 134returns immediately. 135This flag also has the effect of making all subsequent I/O on the open file non-blocking. 136If the 137.Dv O_SYNC 138flag is set, all I/O operations on the file will be done synchronously. 139.Pp 140A fifo should either be opened with 141.Dv O_RDONLY 142or with 143.Dv O_WRONLY . 144The behavior for opening a fifo with 145.Dv O_RDWR 146is undefined. 147.Pp 148When opening a file, a lock with 149.Xr flock 2 150semantics can be obtained by setting 151.Dv O_SHLOCK 152for a shared lock, or 153.Dv O_EXLOCK 154for an exclusive lock. 155If creating a file with 156.Dv O_CREAT , 157the request for the lock will never fail 158(provided that the underlying filesystem supports locking). 159.Pp 160If 161.Fn open 162is successful, the file pointer used to mark the current position within 163the file is set to the beginning of the file. 164.Pp 165When a new file is created it is given the group of the directory 166which contains it. 167.Pp 168The new descriptor is set to remain open across 169.Xr execve 2 170system calls; see 171.Xr close 2 172and 173.Xr fcntl 2 . 174.Pp 175The system imposes a limit on the number of file descriptors 176open simultaneously by one process. 177.Xr getdtablesize 3 178returns the current system limit. 179.Sh RETURN VALUES 180If successful, 181.Fn open 182returns a non-negative integer, termed a file descriptor. 183Otherwise, a value of \-1 is returned and 184.Va errno 185is set to indicate the error. 186.Sh ERRORS 187The named file is opened unless: 188.Bl -tag -width Er 189.It Bq Er ENOTDIR 190A component of the path prefix is not a directory. 191.It Bq Er ENAMETOOLONG 192A component of a pathname exceeded 193.Dv {NAME_MAX} 194characters, or an entire path name exceeded 195.Dv {PATH_MAX} 196characters. 197.It Bq Er ENOENT 198.Dv O_CREAT 199is not set and the named file does not exist. 200.It Bq Er ENOENT 201A component of the path name that must exist does not exist. 202.It Bq Er EACCES 203Search permission is denied for a component of the path prefix. 204.It Bq Er EACCES 205The required permissions (for reading and/or writing) 206are denied for the given flags. 207.It Bq Er EACCES 208.Dv O_CREAT 209is specified, 210the file does not exist, 211and the directory in which it is to be created 212does not permit writing. 213.It Bq Er ELOOP 214Too many symbolic links were encountered in translating the pathname, 215or the 216.Dv O_NOFOLLOW 217flag was specified and the target is a symbolic link. 218.It Bq Er EISDIR 219The named file is a directory, and the arguments specify 220it is to be opened for writing. 221.It Bq Er EINVAL 222The flags specified for opening the file are not valid. 223.It Bq Er EROFS 224The named file resides on a read-only file system, 225and the file is to be modified. 226.It Bq Er EMFILE 227The process has already reached its limit for open file descriptors. 228.It Bq Er ENFILE 229The system file table is full. 230.It Bq Er ENXIO 231The named file is a character special or block 232special file, and the device associated with this special file 233does not exist. 234.It Bq Er EINTR 235The 236.Fn open 237operation was interrupted by a signal. 238.It Bq Er EOPNOTSUPP 239.Dv O_SHLOCK 240or 241.Dv O_EXLOCK 242is specified but the underlying filesystem does not support locking. 243.It Bq Er EWOULDBLOCK 244.Dv O_NONBLOCK 245and one of 246.Dv O_SHLOCK 247or 248.Dv O_EXLOCK 249is specified and the file is locked. 250.It Bq Er ENOSPC 251.Dv O_CREAT 252is specified, 253the file does not exist, 254and the directory in which the entry for the new file is being placed 255cannot be extended because there is no space left on the file 256system containing the directory. 257.It Bq Er ENOSPC 258.Dv O_CREAT 259is specified, 260the file does not exist, 261and there are no free inodes on the file system on which the 262file is being created. 263.It Bq Er EDQUOT 264.Dv O_CREAT 265is specified, 266the file does not exist, 267and the directory in which the entry for the new file 268is being placed cannot be extended because the 269user's quota of disk blocks on the file system 270containing the directory has been exhausted. 271.It Bq Er EDQUOT 272.Dv O_CREAT 273is specified, 274the file does not exist, 275and the user's quota of inodes on the file system on 276which the file is being created has been exhausted. 277.It Bq Er EIO 278An I/O error occurred while making the directory entry or 279allocating the inode for 280.Dv O_CREAT . 281.It Bq Er ETXTBSY 282The file is a pure procedure (shared text) file that is being 283executed and the 284.Fn open 285call requests write access. 286.It Bq Er EFAULT 287.Fa path 288points outside the process's allocated address space. 289.It Bq Er EEXIST 290.Dv O_CREAT 291and 292.Dv O_EXCL 293were specified and the file exists. 294.It Bq Er EOPNOTSUPP 295An attempt was made to open a socket (not currently implemented). 296.It Bq Er EAGAIN 297.Dv O_NONBLOCK 298and either 299.Dv O_EXLOCK 300or 301.Dv O_SHLOCK 302are set and the file is already locked. 303.El 304.Sh SEE ALSO 305.Xr chmod 2 , 306.Xr close 2 , 307.Xr dup 2 , 308.Xr flock 2 , 309.Xr lseek 2 , 310.Xr read 2 , 311.Xr umask 2 , 312.Xr write 2 , 313.Xr getdtablesize 3 314.Sh STANDARDS 315The 316.Fn open 317function conforms to 318.St -ansiC , 319.St -p1003.1-90 320and 321.St -xpg4.2 . 322.Pp 323.Dv POSIX 324specifies three different flavors for synchronous I/O: 325.Dv O_SYNC , 326.Dv O_DSYNC , 327and 328.Dv O_RSYNC . 329In 330.Ox , 331these are all equivalent. 332.Pp 333The 334.Dv O_SHLOCK , 335.Dv O_EXLOCK , 336and 337.Dv O_NOFOLLOW 338flags are non-standard extensions and should not be used if portability 339is of concern. 340.Sh HISTORY 341An 342.Fn open 343function call appeared in 344.At v6 . 345.Sh CAVEATS 346The 347.Dv O_TRUNC 348flag requires that one of 349.Dv O_RDWR 350or 351.Dv O_WRONLY 352also be specified, else 353.Dv EINVAL 354is returned. 355