1.\" $OpenBSD: open.2,v 1.42 2013/01/19 07:57:21 jmc 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: January 19 2013 $ 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.Fd #include <fcntl.h> 42.Ft int 43.Fn open "const char *path" "int flags" "mode_t mode" 44.Ft int 45.Fn openat "int fd" "const char *path" "int flags" "mode_t mode" 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 mode 60.Fa mode 61as described in 62.Xr chmod 2 63and modified by the process' umask value (see 64.Xr umask 2 ) . 65.Pp 66The flags specified are formed by bitwise-inclusive 67.Tn OR Ns 'ing 68the following values defined in 69.In fcntl.h . 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. 90.It Dv O_TRUNC 91Truncate size to 0. 92.It Dv O_EXCL 93Error if create and file exists. 94.It Dv O_SYNC 95Perform synchronous I/O operations. 96.It Dv O_SHLOCK 97Atomically obtain a shared lock. 98.It Dv O_EXLOCK 99Atomically obtain an exclusive lock. 100.It Dv O_NOFOLLOW 101If last path element is a symlink, don't follow it. 102.It Dv O_CLOEXEC 103Set 104.Dv FD_CLOEXEC 105(the close-on-exec flag) 106on the new file descriptor. 107.It Dv O_DIRECTORY 108Error if 109.Fa path 110does not name a directory. 111.El 112.Pp 113Opening a file with 114.Dv O_APPEND 115set causes each write on the file 116to be appended to the end. 117If 118.Dv O_TRUNC 119and a writing mode are specified and the 120file exists, the file is truncated to zero length. 121If 122.Dv O_EXCL 123is set with 124.Dv O_CREAT 125and the file already 126exists, 127.Fn open 128returns an error. 129This may be used to implement a simple exclusive access locking mechanism. 130If either of 131.Dv O_EXCL 132or 133.Dv O_NOFOLLOW 134are set and the last component of the pathname is 135a symbolic link, 136.Fn open 137will fail even if the symbolic 138link points to a non-existent name. 139If the 140.Dv O_NONBLOCK 141flag is specified, do not wait for the device or file to be ready or 142available. 143If the 144.Fn open 145call would result 146in the process being blocked for some reason (e.g., waiting for 147carrier on a dialup line), 148.Fn open 149returns immediately. 150This flag also has the effect of making all subsequent I/O on the open file 151non-blocking. 152If the 153.Dv O_SYNC 154flag is set, all I/O operations on the file will be done synchronously. 155.Pp 156A FIFO should either be opened with 157.Dv O_RDONLY 158or with 159.Dv O_WRONLY . 160The behavior for opening a FIFO with 161.Dv O_RDWR 162is undefined. 163.Pp 164When opening a file, a lock with 165.Xr flock 2 166semantics can be obtained by setting 167.Dv O_SHLOCK 168for a shared lock, or 169.Dv O_EXLOCK 170for an exclusive lock. 171If creating a file with 172.Dv O_CREAT , 173the request for the lock will never fail 174(provided that the underlying filesystem supports locking). 175.Pp 176If 177.Fn open 178is successful, the file pointer used to mark the current position within 179the file is set to the beginning of the file. 180.Pp 181When a new file is created it is given the group of the directory 182which contains it. 183.Pp 184The new descriptor is set to remain open across 185.Xr execve 2 186system calls; see 187.Xr close 2 188and 189.Xr fcntl 2 . 190.Pp 191The system imposes a limit on the number of file descriptors 192open simultaneously by one process. 193.Xr getdtablesize 3 194returns the current system limit. 195.Pp 196The 197.Fn openat 198function is equivalent to 199.Fn open 200except that where 201.Fa path 202specifies a relative path, 203the file to be opened is determined relative to 204the directory associated with file descriptor 205.Fa fd 206instead of the current working directory. 207.Pp 208If 209.Fn openat 210is passed the special value 211.Dv AT_FDCWD 212(defined in 213.In fcntl.h ) 214in the 215.Fa fd 216parameter, the current working directory is used 217and the behavior is identical to a call to 218.Fn open . 219.Sh RETURN VALUES 220If successful, 221.Fn open 222returns a non-negative integer, termed a file descriptor. 223Otherwise, a value of \-1 is returned and 224.Va errno 225is set to indicate the error. 226.Sh ERRORS 227The 228.Fn open 229and 230.Fn openat 231functions will fail if: 232.Bl -tag -width Er 233.It Bq Er ENOTDIR 234A component of the path prefix is not a directory. 235.It Bq Er ENOTDIR 236.Dv O_DIRECTORY 237is specified and 238.Fa path 239does not name a directory. 240.It Bq Er ENAMETOOLONG 241A component of a pathname exceeded 242.Dv {NAME_MAX} 243characters, or an entire path name exceeded 244.Dv {PATH_MAX} 245characters. 246.It Bq Er ENOENT 247.Dv O_CREAT 248is not set and the named file does not exist. 249.It Bq Er ENOENT 250A component of the path name that must exist does not exist. 251.It Bq Er EACCES 252Search permission is denied for a component of the path prefix. 253.It Bq Er EACCES 254The required permissions (for reading and/or writing) 255are denied for the given flags. 256.It Bq Er EACCES 257.Dv O_CREAT 258is specified, 259the file does not exist, 260and the directory in which it is to be created 261does not permit writing. 262.It Bq Er ELOOP 263Too many symbolic links were encountered in translating the pathname, 264or the 265.Dv O_NOFOLLOW 266flag was specified and the target is a symbolic link. 267.It Bq Er EISDIR 268The named file is a directory, and the arguments specify 269it is to be opened for writing. 270.It Bq Er EINVAL 271The flags specified for opening the file are not valid. 272.It Bq Er EROFS 273The named file resides on a read-only file system, 274and the file is to be modified. 275.It Bq Er EMFILE 276The process has already reached its limit for open file descriptors. 277.It Bq Er ENFILE 278The system file table is full. 279.It Bq Er ENXIO 280The named file is a character special or block 281special file, and the device associated with this special file 282does not exist. 283.It Bq Er ENXIO 284The named file is a FIFO, the 285.Dv O_NONBLOCK 286and 287.Dv O_WRONLY 288flags are set, and no process has the file open for reading. 289.It Bq Er EINTR 290The 291.Fn open 292operation was interrupted by a signal. 293.It Bq Er EOPNOTSUPP 294.Dv O_SHLOCK 295or 296.Dv O_EXLOCK 297is specified but the underlying filesystem does not support locking. 298.It Bq Er EWOULDBLOCK 299.Dv O_NONBLOCK 300and one of 301.Dv O_SHLOCK 302or 303.Dv O_EXLOCK 304is specified and the file is already locked. 305.It Bq Er ENOSPC 306.Dv O_CREAT 307is specified, 308the file does not exist, 309and the directory in which the entry for the new file is being placed 310cannot be extended because there is no space left on the file 311system containing the directory. 312.It Bq Er ENOSPC 313.Dv O_CREAT 314is specified, 315the file does not exist, 316and there are no free inodes on the file system on which the 317file is being created. 318.It Bq Er EDQUOT 319.Dv O_CREAT 320is specified, 321the file does not exist, 322and the directory in which the entry for the new file 323is being placed cannot be extended because the 324user's quota of disk blocks on the file system 325containing the directory has been exhausted. 326.It Bq Er EDQUOT 327.Dv O_CREAT 328is specified, 329the file does not exist, 330and the user's quota of inodes on the file system on 331which the file is being created has been exhausted. 332.It Bq Er EIO 333An I/O error occurred while making the directory entry or 334allocating the inode for 335.Dv O_CREAT . 336.It Bq Er ETXTBSY 337The file is a pure procedure (shared text) file that is being 338executed and the 339.Fn open 340call requests write access. 341.It Bq Er EFAULT 342.Fa path 343points outside the process's allocated address space. 344.It Bq Er EEXIST 345.Dv O_CREAT 346and 347.Dv O_EXCL 348were specified and the file exists. 349.It Bq Er EPERM 350The file named by 351.Fa path 352is flagged append-only but 353.Dv O_APPEND 354was not specified in 355.Fa flags . 356.It Bq Er EOPNOTSUPP 357An attempt was made to open a socket (not currently implemented). 358.It Bq Er EBUSY 359An attempt was made to open a terminal device that requires exclusive 360access and the specified device has already be opened. 361.El 362.Pp 363Additionally, the 364.Fn openat 365function will fail if: 366.Bl -tag -width Er 367.It Bq Er EBADF 368The 369.Fa path 370argument does not specify an absolute path and the 371.Fa fd 372argument is neither 373.Dv AT_FDCWD 374nor a valid file descriptor open for reading. 375.El 376.Sh SEE ALSO 377.Xr chflags 2 , 378.Xr chmod 2 , 379.Xr close 2 , 380.Xr dup 2 , 381.Xr flock 2 , 382.Xr lseek 2 , 383.Xr read 2 , 384.Xr umask 2 , 385.Xr write 2 , 386.Xr getdtablesize 3 387.Sh STANDARDS 388The 389.Fn open 390and 391.Fn openat 392functions conform to 393.St -p1003.1-2008 . 394.Pp 395.Dv POSIX 396specifies three different flavors for synchronous I/O: 397.Dv O_SYNC , 398.Dv O_DSYNC , 399and 400.Dv O_RSYNC . 401In 402.Ox , 403these are all equivalent. 404.Pp 405The 406.Dv O_SHLOCK 407and 408.Dv O_EXLOCK 409flags are non-standard extensions and should not be used if portability 410is of concern. 411.Sh HISTORY 412An 413.Fn open 414system call first appeared in 415.At v1 . 416The 417.Fa flags 418arguments has been supported since 419.Bx 4.2 . 420The 421.Fn openat 422function call appeared in 423.Ox 5.0 . 424.Sh CAVEATS 425The 426.Dv O_TRUNC 427flag requires that one of 428.Dv O_RDWR 429or 430.Dv O_WRONLY 431also be specified, else 432.Dv EINVAL 433is returned. 434