1.\" $OpenBSD: open.2,v 1.48 2014/11/25 15:02:13 schwarze 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. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)open.2 8.2 (Berkeley) 11/16/93 32.\" 33.Dd $Mdocdate: November 25 2014 $ 34.Dt OPEN 2 35.Os 36.Sh NAME 37.Nm open , 38.Nm openat 39.Nd open or create a file for reading or writing 40.Sh SYNOPSIS 41.In fcntl.h 42.Ft int 43.Fn open "const char *path" "int flags" ... 44.Ft int 45.Fn openat "int fd" "const char *path" "int flags" ... 46.Sh DESCRIPTION 47The file name specified by 48.Fa path 49is opened 50for reading and/or writing as specified by the 51argument 52.Fa flags 53and the file descriptor returned to the calling process. 54The 55.Fa flags 56argument may indicate the file is to be 57created if it does not exist (by specifying the 58.Dv O_CREAT 59flag), in which case the file is created with a mode 60specified by an additional argument of type 61.Vt mode_t 62as described in 63.Xr chmod 2 64and modified by the process' umask value (see 65.Xr umask 2 ) . 66.Pp 67The 68.Fa flags 69specified are a bitwise OR of the following values. 70Exactly one of the first three values (file access modes) must be specified: 71.Pp 72.Bl -tag -width O_DIRECTORY -offset indent -compact 73.It Dv O_RDONLY 74Open for reading only. 75.It Dv O_WRONLY 76Open for writing only. 77.It Dv O_RDWR 78Open for reading and writing. 79.El 80.Pp 81Any combination of the following flags may additionally be used: 82.Pp 83.Bl -tag -width O_DIRECTORY -offset indent -compact 84.It Dv O_NONBLOCK 85Do not block on open or for data to become available. 86.It Dv O_APPEND 87Append on each write. 88.It Dv O_CREAT 89Create file if it does not exist. 90An additional argument of type 91.Vt mode_t 92must be supplied to the call. 93.It Dv O_TRUNC 94Truncate size to 0. 95.It Dv O_EXCL 96Error if 97.Dv O_CREAT 98is set and file exists. 99.It Dv O_SYNC 100Perform synchronous I/O operations. 101.It Dv O_SHLOCK 102Atomically obtain a shared lock. 103.It Dv O_EXLOCK 104Atomically obtain an exclusive lock. 105.It Dv O_NOFOLLOW 106If last path element is a symlink, don't follow it. 107.It Dv O_CLOEXEC 108Set 109.Dv FD_CLOEXEC 110(the close-on-exec flag) 111on the new file descriptor. 112.It Dv O_DIRECTORY 113Error if 114.Fa path 115does not name a directory. 116.El 117.Pp 118Opening a file with 119.Dv O_APPEND 120set causes each write on the file 121to be appended to the end. 122If 123.Dv O_TRUNC 124and a writing mode are specified and the 125file exists, the file is truncated to zero length. 126If 127.Dv O_EXCL 128is set with 129.Dv O_CREAT 130and the file already 131exists, 132.Fn open 133returns an error. 134This may be used to implement a simple exclusive access locking mechanism. 135If either of 136.Dv O_EXCL 137or 138.Dv O_NOFOLLOW 139are set and the last component of the pathname is 140a symbolic link, 141.Fn open 142will fail even if the symbolic 143link points to a non-existent name. 144If the 145.Dv O_NONBLOCK 146flag is specified, do not wait for the device or file to be ready or 147available. 148If the 149.Fn open 150call would result 151in the process being blocked for some reason (e.g., waiting for 152carrier on a dialup line), 153.Fn open 154returns immediately. 155This flag also has the effect of making all subsequent I/O on the open file 156non-blocking. 157If the 158.Dv O_SYNC 159flag is set, all I/O operations on the file will be done synchronously. 160.Pp 161A FIFO should either be opened with 162.Dv O_RDONLY 163or with 164.Dv O_WRONLY . 165The behavior for opening a FIFO with 166.Dv O_RDWR 167is undefined. 168.Pp 169When opening a file, a lock with 170.Xr flock 2 171semantics can be obtained by setting 172.Dv O_SHLOCK 173for a shared lock, or 174.Dv O_EXLOCK 175for an exclusive lock. 176If creating a file with 177.Dv O_CREAT , 178the request for the lock will never fail 179(provided that the underlying filesystem supports locking). 180.Pp 181If 182.Fn open 183is successful, the file pointer used to mark the current position within 184the file is set to the beginning of the file. 185.Pp 186When a new file is created it is given the group of the directory 187which contains it. 188.Pp 189The new descriptor is set to remain open across 190.Xr execve 2 191system calls; see 192.Xr close 2 193and 194.Xr fcntl 2 . 195.Pp 196The system imposes a limit on the number of file descriptors 197open simultaneously by one process. 198.Xr getdtablesize 3 199returns the current system limit. 200.Pp 201The 202.Fn openat 203function is equivalent to 204.Fn open 205except that where 206.Fa path 207specifies a relative path, 208the file to be opened is determined relative to 209the directory associated with file descriptor 210.Fa fd 211instead of the current working directory. 212.Pp 213If 214.Fn openat 215is passed the special value 216.Dv AT_FDCWD 217(defined in 218.In fcntl.h ) 219in the 220.Fa fd 221parameter, the current working directory is used 222and the behavior is identical to a call to 223.Fn open . 224.Sh RETURN VALUES 225If successful, 226.Fn open 227returns a non-negative integer, termed a file descriptor. 228Otherwise, a value of \-1 is returned and 229.Va errno 230is set to indicate the error. 231.Sh ERRORS 232The 233.Fn open 234and 235.Fn openat 236functions will fail if: 237.Bl -tag -width Er 238.It Bq Er ENOTDIR 239A component of the path prefix is not a directory. 240.It Bq Er ENOTDIR 241.Dv O_DIRECTORY 242is specified and 243.Fa path 244does not name a directory. 245.It Bq Er ENAMETOOLONG 246A component of a pathname exceeded 247.Dv {NAME_MAX} 248characters, or an entire path name exceeded 249.Dv {PATH_MAX} 250characters. 251.It Bq Er ENOENT 252.Dv O_CREAT 253is not set and the named file does not exist. 254.It Bq Er ENOENT 255A component of the path name that must exist does not exist. 256.It Bq Er EACCES 257Search permission is denied for a component of the path prefix. 258.It Bq Er EACCES 259The required permissions (for reading and/or writing) 260are denied for the given 261.Fa flags . 262.It Bq Er EACCES 263.Dv O_CREAT 264is specified, 265the file does not exist, 266and the directory in which it is to be created 267does not permit writing. 268.It Bq Er ELOOP 269Too many symbolic links were encountered in translating the pathname, 270or the 271.Dv O_NOFOLLOW 272flag was specified and the target is a symbolic link. 273.It Bq Er EISDIR 274The named file is a directory, and the arguments specify 275it is to be opened for writing. 276.It Bq Er EINVAL 277The 278.Fa flags 279specified for opening the file are not valid. 280.It Bq Er EROFS 281The named file resides on a read-only file system, 282and the file is to be modified. 283.It Bq Er EMFILE 284The process has already reached its limit for open file descriptors. 285.It Bq Er ENFILE 286The system file table is full. 287.It Bq Er ENXIO 288The named file is a character special or block 289special file, and the device associated with this special file 290does not exist. 291.It Bq Er ENXIO 292The named file is a FIFO, the 293.Dv O_NONBLOCK 294and 295.Dv O_WRONLY 296flags are set, and no process has the file open for reading. 297.It Bq Er EINTR 298The 299.Fn open 300operation was interrupted by a signal. 301.It Bq Er EOPNOTSUPP 302.Dv O_SHLOCK 303or 304.Dv O_EXLOCK 305is specified but the underlying filesystem does not support locking. 306.It Bq Er EWOULDBLOCK 307.Dv O_NONBLOCK 308and one of 309.Dv O_SHLOCK 310or 311.Dv O_EXLOCK 312is specified and the file is already locked. 313.It Bq Er ENOSPC 314.Dv O_CREAT 315is specified, 316the file does not exist, 317and the directory in which the entry for the new file is being placed 318cannot be extended because there is no space left on the file 319system containing the directory. 320.It Bq Er ENOSPC 321.Dv O_CREAT 322is specified, 323the file does not exist, 324and there are no free inodes on the file system on which the 325file is being created. 326.It Bq Er EDQUOT 327.Dv O_CREAT 328is specified, 329the file does not exist, 330and the directory in which the entry for the new file 331is being placed cannot be extended because the 332user's quota of disk blocks on the file system 333containing the directory has been exhausted. 334.It Bq Er EDQUOT 335.Dv O_CREAT 336is specified, 337the file does not exist, 338and the user's quota of inodes on the file system on 339which the file is being created has been exhausted. 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 ETXTBSY 345The file is a pure procedure (shared text) file that is being 346executed and the 347.Fn open 348call requests write access. 349.It Bq Er EFAULT 350.Fa path 351points outside the process's allocated address space. 352.It Bq Er EEXIST 353.Dv O_CREAT 354and 355.Dv O_EXCL 356were specified and the file exists. 357.It Bq Er EPERM 358The file named by 359.Fa path 360is flagged append-only but 361.Dv O_APPEND 362was not specified in 363.Fa flags . 364.It Bq Er EOPNOTSUPP 365An attempt was made to open a socket (not currently implemented). 366.It Bq Er EBUSY 367An attempt was made to open a terminal device that requires exclusive 368access and the specified device has already be opened. 369.El 370.Pp 371Additionally, the 372.Fn openat 373function will fail if: 374.Bl -tag -width Er 375.It Bq Er EBADF 376The 377.Fa path 378argument specifies a relative path and the 379.Fa fd 380argument is neither 381.Dv AT_FDCWD 382nor a valid file descriptor. 383.It Bq Er ENOTDIR 384The 385.Fa path 386argument specifies a relative path and the 387.Fa fd 388argument is a valid file descriptor but it does not reference a directory. 389.It Bq Er EACCES 390The 391.Fa path 392argument specifies a relative path but search permission is denied 393for the directory which the 394.Fa fd 395file descriptor references. 396.El 397.Sh SEE ALSO 398.Xr chflags 2 , 399.Xr chmod 2 , 400.Xr close 2 , 401.Xr dup 2 , 402.Xr flock 2 , 403.Xr lseek 2 , 404.Xr read 2 , 405.Xr umask 2 , 406.Xr write 2 , 407.Xr getdtablesize 3 408.Sh STANDARDS 409The 410.Fn open 411and 412.Fn openat 413functions conform to 414.St -p1003.1-2008 . 415.Pp 416.Dv POSIX 417specifies three different flavors for synchronous I/O: 418.Dv O_SYNC , 419.Dv O_DSYNC , 420and 421.Dv O_RSYNC . 422In 423.Ox , 424these are all equivalent. 425.Pp 426The 427.Dv O_SHLOCK 428and 429.Dv O_EXLOCK 430flags are non-standard extensions and should not be used if portability 431is of concern. 432.Sh HISTORY 433An 434.Fn open 435system call first appeared in 436.At v1 . 437The 438.Fa flags 439argument has been supported since 440.Bx 4.2 . 441Before that, a dedicated 442.Fn creat 443system call had to be used to create new files; 444it appeared in 445.At v1 , 446was deprecated in 447.Bx 4.3 Reno , 448and removed in 449.Ox 5.0 . 450.Pp 451The 452.Fn openat 453system call has been available since 454.Ox 5.0 . 455.Sh CAVEATS 456The 457.Dv O_TRUNC 458flag requires that one of 459.Dv O_RDWR 460or 461.Dv O_WRONLY 462also be specified, else 463.Er EINVAL 464is returned. 465