1.\" $NetBSD: open.2,v 1.59 2017/11/13 09:04:57 wiz 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 November 9, 2017 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_REGULAR 192Fail if the path does not refer to a regular file. 193.It Dv O_ASYNC 194Enable the 195.Dv SIGIO 196signal to be sent to the process group 197when I/O is possible, e.g., 198upon availability of data to be read. 199.\" (This block awaits a decision about the semantics of O_SEARCH) 200.\" .It Dv O_SEARCH 201.\" If opening a directory, search permission checks will not be performed on 202.\" subsequent usage of the file descriptor for looking up relative paths by 203.\" .Xr faccessat 2 , 204.\" .Xr fchmodat 2 , 205.\" .Xr fchownat 2 , 206.\" .Xr fstatat 2 , 207.\" .Xr linkat 2 , 208.\" .Xr mkdirat 2 , 209.\" .Xr mkfifoat 2 , 210.\" .Xr mknodat 2 , 211.\" .Xr openat 2 , 212.\" .Xr readlinkat 2 , 213.\" .Xr symlinkat 2 , 214.\" .Xr unlinkat 2 , 215.\" and 216.\" .Xr utimensat 2 . 217.El 218.Pp 219Opening a file with 220.Dv O_APPEND 221set causes each write on the file 222to be appended to the end. 223If 224.Dv O_TRUNC 225is specified and the 226file exists, the file is truncated to zero length. 227.Pp 228If 229.Dv O_EXCL 230is set with 231.Dv O_CREAT 232and the file already 233exists, 234.Fn open 235returns an error. 236This may be used to implement a simple exclusive access locking mechanism. 237If 238.Dv O_EXCL 239is set and the last component of the pathname is 240a symbolic link, 241.Fn open 242will fail even if the symbolic 243link points to a non-existent name. 244.Pp 245If the 246.Dv O_NONBLOCK 247flag is specified, do not wait for the device or file to be ready or 248available. 249If the 250.Fn open 251call would result 252in the process being blocked for some reason (e.g., waiting for 253carrier on a dialup line), 254.Fn open 255returns immediately. 256This flag also has the effect of making all subsequent I/O on the open file non-blocking. 257.Pp 258When opening a file, a lock with 259.Xr flock 2 260semantics can be obtained by setting 261.Dv O_SHLOCK 262for a shared lock, or 263.Dv O_EXLOCK 264for an exclusive lock. 265If creating a file with 266.Dv O_CREAT , 267the request for the lock will never fail 268(provided that the underlying file system supports locking). 269.Pp 270If 271.Fn open 272is successful, the file pointer used to mark the current position within 273the file is set to the beginning of the file. 274.Pp 275When a new file is created it is given the group of the directory 276which contains it. 277.Pp 278The new descriptor is set to remain open across 279.Xr execve 2 280system calls; see 281.Xr close 2 282and 283.Xr fcntl 2 . 284.Pp 285The system imposes a limit on the number of file descriptors 286open simultaneously by one process. 287Calling 288.Xr getdtablesize 3 289returns the current system limit. 290.Sh RETURN VALUES 291If successful, 292.Fn open 293and 294.Fn openat 295returns a non-negative integer, termed a file descriptor. 296Otherwise, a value of \-1 is returned and 297.Va errno 298is set to indicate the error. 299.Sh ERRORS 300The named file is opened unless: 301.Bl -tag -width Er 302.It Bq Er EACCES 303Search permission is denied for a component of the path prefix, 304the required permissions (for reading and/or writing) 305are denied for the given flags, or 306.Dv O_CREAT 307is specified, 308the file does not exist, 309and the directory in which it is to be created 310does not permit writing. 311.It Bq Er EDQUOT 312.Dv O_CREAT 313is specified, 314the file does not exist, 315and the directory in which the entry for the new file 316is being placed cannot be extended because the 317user's quota of disk blocks on the file system 318containing the directory has been exhausted; or 319.Dv O_CREAT 320is specified, 321the file does not exist, 322and the user's quota of inodes on the file system on 323which the file is being created has been exhausted. 324.It Bq Er EEXIST 325.Dv O_CREAT 326and 327.Dv O_EXCL 328were specified and the file exists. 329.It Bq Er EFAULT 330.Fa path 331points outside the process's allocated address space. 332.It Bq Er EFTYPE 333.Dv O_NOFOLLOW 334was specified, but the last path component is a symlink. 335.Em Note : 336.St -p1003.1-2008 337specifies returning 338.Bq Er ELOOP 339for this case. 340.It Bq Er EINTR 341The 342.Fn open 343operation was interrupted by a signal. 344.It Bq Er EIO 345An I/O error occurred while making the directory entry or 346allocating the inode for 347.Dv O_CREAT . 348.It Bq Er EISDIR 349The named file is a directory, and the arguments specify 350it is to be opened for writing. 351.It Bq Er ELOOP 352Too many symbolic links were encountered in translating the pathname. 353.It Bq Er EMFILE 354The process has already reached its limit for open file descriptors. 355.It Bq Er ENAMETOOLONG 356A component of a pathname exceeded 357.Brq Dv NAME_MAX 358characters, or an entire path name exceeded 359.Brq Dv PATH_MAX 360characters. 361.It Bq Er ENFILE 362The system file table is full. 363.It Bq Er ENOENT 364.Dv O_CREAT 365is not set and the named file does not exist, or 366a component of the path name that must exist does not exist. 367.It Bq Er ENOSPC 368.Dv O_CREAT 369is specified, 370the file does not exist, 371and the directory in which the entry for the new file is being placed 372cannot be extended because there is no space left on the file 373system containing the directory; or 374.Dv O_CREAT 375is specified, 376the file does not exist, 377and there are no free inodes on the file system on which the 378file is being created. 379.It Bq Er ENOTDIR 380A component of the path prefix is not a directory; or 381.Dv O_DIRECTORY 382is specified and the last path component is not a directory. 383.It Bq Er ENXIO 384The named file is a character special or block 385special file, and the device associated with this special file 386does not exist, or the named file is a 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 file system 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