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