1.\" $NetBSD: open.2,v 1.55 2013/01/13 08:15:02 dholland 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 18, 2012 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 291returns a non-negative integer, termed a file descriptor. 292Otherwise, a value of \-1 is returned and 293.Va errno 294is set to indicate the error. 295.Sh ERRORS 296The named file is opened unless: 297.Bl -tag -width Er 298.It Bq Er EACCES 299Search permission is denied for a component of the path prefix, 300the required permissions (for reading and/or writing) 301are denied for the given flags, or 302.Dv O_CREAT 303is specified, 304the file does not exist, 305and the directory in which it is to be created 306does not permit writing. 307.It Bq Er EDQUOT 308.Dv O_CREAT 309is specified, 310the file does not exist, 311and the directory in which the entry for the new file 312is being placed cannot be extended because the 313user's quota of disk blocks on the file system 314containing the directory has been exhausted; or 315.Dv O_CREAT 316is specified, 317the file does not exist, 318and the user's quota of inodes on the file system on 319which the file is being created has been exhausted. 320.It Bq Er EEXIST 321.Dv O_CREAT 322and 323.Dv O_EXCL 324were specified and the file exists. 325.It Bq Er EFAULT 326.Fa path 327points outside the process's allocated address space. 328.It Bq Er EFTYPE 329.Dv O_NOFOLLOW 330was specified, but the last path component is a symlink. 331.Em Note : 332.St -p1003.1-2008 333specifies returning 334.Bq Er ELOOP 335for this case. 336.It Bq Er EINTR 337The 338.Fn open 339operation was interrupted by a signal. 340.It Bq Er EIO 341An I/O error occurred while making the directory entry or 342allocating the inode for 343.Dv O_CREAT . 344.It Bq Er EISDIR 345The named file is a directory, and the arguments specify 346it is to be opened for writing. 347.It Bq Er ELOOP 348Too many symbolic links were encountered in translating the pathname. 349.It Bq Er EMFILE 350The process has already reached its limit for open file descriptors. 351.It Bq Er ENAMETOOLONG 352A component of a pathname exceeded 353.Brq Dv NAME_MAX 354characters, or an entire path name exceeded 355.Brq Dv PATH_MAX 356characters. 357.It Bq Er ENFILE 358The system file table is full. 359.It Bq Er ENOENT 360.Dv O_CREAT 361is not set and the named file does not exist, or 362a component of the path name that must exist does not exist. 363.It Bq Er ENOSPC 364.Dv O_CREAT 365is specified, 366the file does not exist, 367and the directory in which the entry for the new file is being placed 368cannot be extended because there is no space left on the file 369system containing the directory; or 370.Dv O_CREAT 371is specified, 372the file does not exist, 373and there are no free inodes on the file system on which the 374file is being created. 375.It Bq Er ENOTDIR 376A component of the path prefix is not a directory; or 377.Dv O_DIRECTORY 378is specified and the last path component is not a directory. 379.It Bq Er ENXIO 380The named file is a character special or block 381special file, and the device associated with this special file 382does not exist, or 383the named file is a 384.Tn FIFO , 385.Dv O_NONBLOCK 386and 387.Dv O_WRONLY 388is set and no process has the file open for reading. 389.It Bq Er EOPNOTSUPP 390.Dv O_SHLOCK 391or 392.Dv O_EXLOCK 393is specified but the underlying filesystem does not support locking; or 394an attempt was made to open a socket (not currently implemented). 395.It Bq Er EPERM 396The file's flags (see 397.Xr chflags 2 ) 398don't allow the file to be opened. 399.It Bq Er EROFS 400The named file resides on a read-only file system, 401and the file is to be modified. 402.It Bq Er ETXTBSY 403The file is a pure procedure (shared text) file that is being 404executed and the 405.Fn open 406call requests write access. 407.El 408.Sh SEE ALSO 409.Xr chmod 2 , 410.Xr close 2 , 411.Xr dup 2 , 412.Xr faccessat 2 , 413.Xr fchmodat 2 , 414.Xr fchownat 2 , 415.Xr fstatat 2 , 416.Xr linkat 2 , 417.Xr lseek 2 , 418.Xr mkdirat 2 , 419.Xr mkfifoat 2 , 420.Xr mknodat 2 , 421.Xr openat 2 , 422.Xr read 2 , 423.Xr readlinkat 2 , 424.Xr symlinkat 2 , 425.Xr umask 2 , 426.Xr unlinkat 2 , 427.Xr utimensat 2 , 428.Xr write 2 , 429.Xr getdtablesize 3 430.Sh STANDARDS 431The 432.Fn open 433function conforms to 434.St -p1003.1-90 . 435.Fn openat 436conforms to 437.St -p1003.1-2008 . 438.Pp 439The 440.Fa flags 441values 442.Dv O_DSYNC , 443.Dv O_SYNC 444and 445.Dv O_RSYNC 446are extensions defined in 447.St -p1003.1b-93 . 448.\" (This block awaits a decision about the semantics of O_SEARCH) 449.\" .Dv O_SEARCH 450.\" is defined in 451.\" .St -p1003.1-2008 . 452.Pp 453The 454.Dv O_SHLOCK 455and 456.Dv O_EXLOCK 457flags are non-standard extensions and should not be used if portability 458is of concern. 459.Sh HISTORY 460An 461.Fn open 462function call appeared in 463.At v2 . 464