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