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