1.\" $NetBSD: open.2,v 1.56 2013/07/29 18:37:16 njoly 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 July 29, 2013 33.Dt OPEN 2 34.Os 35.Sh NAME 36.Nm open , 37.Nm openat 38.Nd open or create a file for reading or writing 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In fcntl.h 43.Ft int 44.Fn open "const char *path" "int flags" "..." 45.Ft int 46.Fn openat "int fd" "const char *path" "int flags" "..." 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. 55.Pp 56.Fn openat 57works the same way as 58.Fn open 59except if 60.Fa path 61is relative. 62In that case, it is looked up from a directory whose file 63descriptor was passed as 64.Fa fd . 65Search permission is required on this directory. 66.\" (These alternatives await a decision about the semantics of O_SEARCH) 67.\" Search permission is required on this directory 68.\" except if 69.\" .Fa fd 70.\" was opened with the 71.\" .Dv O_SEARCH 72.\" flag. 73.\" - or - 74.\" This file descriptor must have been opened with the 75.\" .Dv O_SEARCH 76.\" flag. 77.Fa fd 78can be set to 79.Dv AT_FDCWD 80in order to specify the current directory. 81.Pp 82The 83.Fa flags 84are specified by 85.Em or Ns 'ing 86the values listed below. 87Applications must specify exactly one of the first three values 88(file access methods): 89.Bl -tag -offset indent -width O_DIRECTORY 90.It Dv O_RDONLY 91Open for reading only. 92.It Dv O_WRONLY 93Open for writing only. 94.It Dv O_RDWR 95Open for reading and writing. 96.El 97.Pp 98Any combination of the following may be used: 99.Bl -tag -offset indent -width O_DIRECTORY 100.It Dv O_NONBLOCK 101Do not block on open or for data to become available. 102.It Dv O_APPEND 103Append to the file on each write. 104.It Dv O_CREAT 105Create the file if it does not exist. 106The third argument of type 107.Ft mode_t 108is used to compute the mode bits of the file as described in 109.Xr chmod 2 110and modified by the process' umask value (see 111.Xr umask 2 ) . 112.It Dv O_TRUNC 113Truncate size to 0. 114.It Dv O_EXCL 115Error if 116.Dv O_CREAT 117and the file already exists. 118.It Dv O_SHLOCK 119Atomically obtain a shared lock. 120.It Dv O_EXLOCK 121Atomically obtain an exclusive lock. 122.It Dv O_NOFOLLOW 123If last path element is a symlink, don't follow it. 124This option is provided for compatibility with other operating 125systems, but its security value is questionable. 126.It Dv O_CLOEXEC 127Set the 128.Xr close 2 129on 130.Xr exec 3 131flag. 132.It Dv O_NOSIGPIPE 133Return 134.Er EPIPE 135instead of raising 136.Dv SIGPIPE . 137.It Dv O_DSYNC 138If set, write operations will be performed according to synchronized 139I/O data integrity completion: 140each write will wait for the file data to be committed to stable 141storage. 142.It Dv O_SYNC 143If set, write operations will be performed according to synchronized 144I/O file integrity completion: 145each write will wait for both the file data and file status to be 146committed to stable storage. 147.It Dv O_RSYNC 148If set, read operations will complete at the same level of 149integrity which is in effect for write operations: 150if specified together with 151.Dv O_SYNC , 152each read will wait for the file status to be committed to stable 153storage. 154.Pp 155Combining 156.Dv O_RSYNC 157with 158.Dv O_DSYNC 159only, or specifying it without any other synchronized I/O integrity 160completion flag set, has no further effect. 161.It Dv O_ALT_IO 162Alternate I/O semantics will be used for read and write operations 163on the file descriptor. 164Alternate semantics are defined by the underlying layers and will not 165have any alternate effect in most cases. 166.It Dv O_NOCTTY 167If the file is a terminal device, the opened device is not 168made the controlling terminal for the session. 169This flag has no effect on 170.Nx , 171since the system defaults to the abovementioned behaviour. 172The flag is present only for standards conformance. 173.It Dv O_DIRECT 174If set on a regular file, data I/O operations will not buffer the data 175being transferred in the kernel's cache, but rather transfer the data 176directly between user memory and the underlying device driver if possible. 177This flag is advisory; the request may be performed in the normal 178buffered fashion if certain conditions are not met, e.g. if the request 179is not sufficiently aligned or if the file is mapped. 180.Pp 181To meet the alignment requirements for direct I/O, the file offset, 182the length of the I/O and the address of the buffer in memory must all 183be multiples of 184.Dv DEV_BSIZE 185(512 bytes). 186If the I/O request is made 187using an interface that supports scatter/gather via struct iovec, each 188element of the request must meet the above alignment constraints. 189.It Dv O_DIRECTORY 190Fail if the file is not a directory. 191.It Dv O_ASYNC 192Enable the 193.Dv SIGIO 194signal to be sent to the process group 195when I/O is possible, e.g., 196upon availability of data to be read. 197.\" (This block awaits a decision about the semantics of O_SEARCH) 198.\" .It Dv O_SEARCH 199.\" If opening a directory, search permission checks will not be performed on 200.\" subsequent usage of the file descriptor for looking up relative paths by 201.\" .Xr faccessat 2 , 202.\" .Xr fchmodat 2 , 203.\" .Xr fchownat 2 , 204.\" .Xr fstatat 2 , 205.\" .Xr linkat 2 , 206.\" .Xr mkdirat 2 , 207.\" .Xr mkfifoat 2 , 208.\" .Xr mknodat 2 , 209.\" .Xr openat 2 , 210.\" .Xr readlinkat 2 , 211.\" .Xr symlinkat 2 , 212.\" .Xr unlinkat 2 , 213.\" and 214.\" .Xr utimensat 2 . 215.El 216.Pp 217Opening a file with 218.Dv O_APPEND 219set causes each write on the file 220to be appended to the end. 221If 222.Dv O_TRUNC 223is specified and the 224file exists, the file is truncated to zero length. 225.Pp 226If 227.Dv O_EXCL 228is set with 229.Dv O_CREAT 230and the file already 231exists, 232.Fn open 233returns an error. 234This may be used to implement a simple exclusive access locking mechanism. 235If 236.Dv O_EXCL 237is set and the last component of the pathname is 238a symbolic link, 239.Fn open 240will fail even if the symbolic 241link points to a non-existent name. 242.Pp 243If the 244.Dv O_NONBLOCK 245flag is specified, do not wait for the device or file to be ready or 246available. 247If the 248.Fn open 249call would result 250in the process being blocked for some reason (e.g., waiting for 251carrier on a dialup line), 252.Fn open 253returns immediately. 254This flag also has the effect of making all subsequent I/O on the open file non-blocking. 255.Pp 256When opening a file, a lock with 257.Xr flock 2 258semantics can be obtained by setting 259.Dv O_SHLOCK 260for a shared lock, or 261.Dv O_EXLOCK 262for an exclusive lock. 263If creating a file with 264.Dv O_CREAT , 265the request for the lock will never fail 266(provided that the underlying filesystem supports locking). 267.Pp 268If 269.Fn open 270is successful, the file pointer used to mark the current position within 271the file is set to the beginning of the file. 272.Pp 273When a new file is created it is given the group of the directory 274which contains it. 275.Pp 276The new descriptor is set to remain open across 277.Xr execve 2 278system calls; see 279.Xr close 2 280and 281.Xr fcntl 2 . 282.Pp 283The system imposes a limit on the number of file descriptors 284open simultaneously by one process. 285Calling 286.Xr getdtablesize 3 287returns the current system limit. 288.Sh RETURN VALUES 289If successful, 290.Fn open 291and 292.Fn openat 293returns a non-negative integer, termed a file descriptor. 294Otherwise, a value of \-1 is returned and 295.Va errno 296is set to indicate the error. 297.Sh ERRORS 298The named file is opened unless: 299.Bl -tag -width Er 300.It Bq Er EACCES 301Search permission is denied for a component of the path prefix, 302the required permissions (for reading and/or writing) 303are denied for the given flags, or 304.Dv O_CREAT 305is specified, 306the file does not exist, 307and the directory in which it is to be created 308does not permit writing. 309.It Bq Er EDQUOT 310.Dv O_CREAT 311is specified, 312the file does not exist, 313and the directory in which the entry for the new file 314is being placed cannot be extended because the 315user's quota of disk blocks on the file system 316containing the directory has been exhausted; or 317.Dv O_CREAT 318is specified, 319the file does not exist, 320and the user's quota of inodes on the file system on 321which the file is being created has been exhausted. 322.It Bq Er EEXIST 323.Dv O_CREAT 324and 325.Dv O_EXCL 326were specified and the file exists. 327.It Bq Er EFAULT 328.Fa path 329points outside the process's allocated address space. 330.It Bq Er EFTYPE 331.Dv O_NOFOLLOW 332was specified, but the last path component is a symlink. 333.Em Note : 334.St -p1003.1-2008 335specifies returning 336.Bq Er ELOOP 337for this case. 338.It Bq Er EINTR 339The 340.Fn open 341operation was interrupted by a signal. 342.It Bq Er EIO 343An I/O error occurred while making the directory entry or 344allocating the inode for 345.Dv O_CREAT . 346.It Bq Er EISDIR 347The named file is a directory, and the arguments specify 348it is to be opened for writing. 349.It Bq Er ELOOP 350Too many symbolic links were encountered in translating the pathname. 351.It Bq Er EMFILE 352The process has already reached its limit for open file descriptors. 353.It Bq Er ENAMETOOLONG 354A component of a pathname exceeded 355.Brq Dv NAME_MAX 356characters, or an entire path name exceeded 357.Brq Dv PATH_MAX 358characters. 359.It Bq Er ENFILE 360The system file table is full. 361.It Bq Er ENOENT 362.Dv O_CREAT 363is not set and the named file does not exist, or 364a component of the path name that must exist does not exist. 365.It Bq Er ENOSPC 366.Dv O_CREAT 367is specified, 368the file does not exist, 369and the directory in which the entry for the new file is being placed 370cannot be extended because there is no space left on the file 371system containing the directory; or 372.Dv O_CREAT 373is specified, 374the file does not exist, 375and there are no free inodes on the file system on which the 376file is being created. 377.It Bq Er ENOTDIR 378A component of the path prefix is not a directory; or 379.Dv O_DIRECTORY 380is specified and the last path component is not a directory. 381.It Bq Er ENXIO 382The named file is a character special or block 383special file, and the device associated with this special file 384does not exist, or 385the named file is a 386.Tn FIFO , 387.Dv O_NONBLOCK 388and 389.Dv O_WRONLY 390is set and no process has the file open for reading. 391.It Bq Er EOPNOTSUPP 392.Dv O_SHLOCK 393or 394.Dv O_EXLOCK 395is specified but the underlying filesystem does not support locking; or 396an attempt was made to open a socket (not currently implemented). 397.It Bq Er EPERM 398The file's flags (see 399.Xr chflags 2 ) 400don't allow the file to be opened. 401.It Bq Er EROFS 402The named file resides on a read-only file system, 403and the file is to be modified. 404.It Bq Er ETXTBSY 405The file is a pure procedure (shared text) file that is being 406executed and the 407.Fn open 408call requests write access. 409.El 410.Pp 411In addition, 412.Fn openat 413will fail if: 414.Bl -tag -width Er 415.It Bq Er EBADF 416.Fa path 417does not specify an absolute path and 418.Fa fd 419is neither 420.Dv AT_FDCWD 421nor a valid file descriptor open for reading or searching. 422.It Bq Er ENOTDIR 423.Fa path 424is not an absolute path and 425.Fa fd 426is a file descriptor associated with a non-directory file. 427.El 428.Sh SEE ALSO 429.Xr chmod 2 , 430.Xr close 2 , 431.Xr dup 2 , 432.Xr faccessat 2 , 433.Xr fchmodat 2 , 434.Xr fchownat 2 , 435.Xr fstatat 2 , 436.Xr linkat 2 , 437.Xr lseek 2 , 438.Xr mkdirat 2 , 439.Xr mkfifoat 2 , 440.Xr mknodat 2 , 441.Xr read 2 , 442.Xr readlinkat 2 , 443.Xr symlinkat 2 , 444.Xr umask 2 , 445.Xr unlinkat 2 , 446.Xr utimensat 2 , 447.Xr write 2 , 448.Xr getdtablesize 3 449.Sh STANDARDS 450The 451.Fn open 452function conforms to 453.St -p1003.1-90 . 454.Fn openat 455conforms to 456.St -p1003.1-2008 . 457.Pp 458The 459.Fa flags 460values 461.Dv O_DSYNC , 462.Dv O_SYNC 463and 464.Dv O_RSYNC 465are extensions defined in 466.St -p1003.1b-93 . 467.\" (This block awaits a decision about the semantics of O_SEARCH) 468.\" .Dv O_SEARCH 469.\" is defined in 470.\" .St -p1003.1-2008 . 471.Pp 472The 473.Dv O_SHLOCK 474and 475.Dv O_EXLOCK 476flags are non-standard extensions and should not be used if portability 477is of concern. 478.Sh HISTORY 479An 480.Fn open 481function call appeared in 482.At v2 . 483