1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)open.2 8.2 (Berkeley) 11/16/93 29.\" $FreeBSD$ 30.\" 31.Dd May 6, 2021 32.Dt OPEN 2 33.Os 34.Sh NAME 35.Nm open , openat 36.Nd open or create a file for reading, writing or executing 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In fcntl.h 41.Ft int 42.Fn open "const char *path" "int flags" "..." 43.Ft int 44.Fn openat "int fd" "const char *path" "int flags" "..." 45.Sh DESCRIPTION 46The file name specified by 47.Fa path 48is opened 49for either execution or reading and/or writing as specified by the 50argument 51.Fa flags 52and the file descriptor returned to the calling process. 53The 54.Fa flags 55argument may indicate the file is to be 56created if it does not exist (by specifying the 57.Dv O_CREAT 58flag). 59In this case 60.Fn open 61and 62.Fn openat 63require an additional argument 64.Fa "mode_t mode" , 65and the file is created with mode 66.Fa mode 67as described in 68.Xr chmod 2 69and modified by the process' umask value (see 70.Xr umask 2 ) . 71.Pp 72The 73.Fn openat 74function is equivalent to the 75.Fn open 76function except in the case where the 77.Fa path 78specifies a relative path. 79For 80.Fn openat 81and relative 82.Fa path , 83the file to be opened is determined relative to the directory 84associated with the file descriptor 85.Fa fd 86instead of the current working directory. 87The 88.Fa flag 89parameter and the optional fourth parameter correspond exactly to 90the parameters of 91.Fn open . 92If 93.Fn openat 94is passed the special value 95.Dv AT_FDCWD 96in the 97.Fa fd 98parameter, the current working directory is used 99and the behavior is identical to a call to 100.Fn open . 101.Pp 102When 103.Fn openat 104is called with an absolute 105.Fa path , 106it ignores the 107.Fa fd 108argument. 109.Pp 110In 111.Xr capsicum 4 112capability mode, 113.Fn open 114is not permitted. 115The 116.Fa path 117argument to 118.Fn openat 119must be strictly relative to a file descriptor 120.Fa fd . 121.Fa path 122must not be an absolute path and must not contain ".." components 123which cause the path resolution to escape the directory hierarchy 124starting at 125.Fa fd . 126Additionally, no symbolic link in 127.Fa path 128may target absolute path or contain escaping ".." components. 129.Fa fd 130must not be 131.Dv AT_FDCWD . 132.Pp 133If the 134.Dv vfs.lookup_cap_dotdot 135.Xr sysctl 3 136MIB is set to zero, ".." components in the paths, 137used in capability mode, 138are completely disabled. 139If the 140.Dv vfs.lookup_cap_dotdot_nonlocal 141MIB is set to zero, ".." is not allowed if found on non-local filesystem. 142.Pp 143The flags specified are formed by 144.Em or Ns 'ing 145the following values 146.Pp 147.Bd -literal -offset indent -compact 148O_RDONLY open for reading only 149O_WRONLY open for writing only 150O_RDWR open for reading and writing 151O_EXEC open for execute only 152O_SEARCH open for search only, an alias for O_EXEC 153O_NONBLOCK do not block on open 154O_APPEND append on each write 155O_CREAT create file if it does not exist 156O_TRUNC truncate size to 0 157O_EXCL error if create and file exists 158O_SHLOCK atomically obtain a shared lock 159O_EXLOCK atomically obtain an exclusive lock 160O_DIRECT eliminate or reduce cache effects 161O_FSYNC synchronous writes (historical synonym for O_SYNC) 162O_SYNC synchronous writes 163O_DSYNC synchronous data writes 164O_NOFOLLOW do not follow symlinks 165O_NOCTTY ignored 166O_TTY_INIT ignored 167O_DIRECTORY error if file is not a directory 168O_CLOEXEC set FD_CLOEXEC upon open 169O_VERIFY verify the contents of the file 170O_RESOLVE_BENEATH path resolution must not cross the fd directory 171O_PATH record only the target path in the opened descriptor 172O_EMPTY_PATH openat, open file referenced by fd if path is empty 173.Ed 174.Pp 175Opening a file with 176.Dv O_APPEND 177set causes each write on the file 178to be appended to the end. 179If 180.Dv O_TRUNC 181is specified and the 182file exists, the file is truncated to zero length. 183If 184.Dv O_EXCL 185is set with 186.Dv O_CREAT 187and the file already 188exists, 189.Fn open 190returns an error. 191This may be used to 192implement a simple exclusive access locking mechanism. 193If 194.Dv O_EXCL 195is set and the last component of the pathname is 196a symbolic link, 197.Fn open 198will fail even if the symbolic 199link points to a non-existent name. 200If the 201.Dv O_NONBLOCK 202flag is specified and the 203.Fn open 204system call would result 205in the process being blocked for some reason (e.g., waiting for 206carrier on a dialup line), 207.Fn open 208returns immediately. 209The descriptor remains in non-blocking mode for subsequent operations. 210.Pp 211If 212.Dv O_SYNC 213is used in the mask, all writes will 214immediately and synchronously be written to disk. 215.Dv O_FSYNC 216is an historical synonym for 217.Dv O_SYNC . 218.Pp 219If 220.Dv O_DSYNC 221is used in the mask, all data and metadata required to read the data will be 222synchronously written to disk, but changes to metadata such as file access and 223modification timestamps may be written later. 224.Pp 225If 226.Dv O_NOFOLLOW 227is used in the mask and the target file passed to 228.Fn open 229is a symbolic link then the 230.Fn open 231will fail. 232.Pp 233When opening a file, a lock with 234.Xr flock 2 235semantics can be obtained by setting 236.Dv O_SHLOCK 237for a shared lock, or 238.Dv O_EXLOCK 239for an exclusive lock. 240If creating a file with 241.Dv O_CREAT , 242the request for the lock will never fail 243(provided that the underlying file system supports locking). 244.Pp 245.Dv O_DIRECT 246may be used to minimize or eliminate the cache effects of reading and writing. 247The system will attempt to avoid caching the data you read or write. 248If it cannot avoid caching the data, 249it will minimize the impact the data has on the cache. 250Use of this flag can drastically reduce performance if not used with care. 251.Pp 252.Dv O_NOCTTY 253may be used to ensure the OS does not assign this file as the 254controlling terminal when it opens a tty device. 255This is the default on 256.Fx , 257but is present for 258.Tn POSIX 259compatibility. 260The 261.Fn open 262system call will not assign controlling terminals on 263.Fx . 264.Pp 265.Dv O_TTY_INIT 266may be used to ensure the OS restores the terminal attributes when 267initially opening a TTY. 268This is the default on 269.Fx , 270but is present for 271.Tn POSIX 272compatibility. 273The initial call to 274.Fn open 275on a TTY will always restore default terminal attributes on 276.Fx . 277.Pp 278.Dv O_DIRECTORY 279may be used to ensure the resulting file descriptor refers to a 280directory. 281This flag can be used to prevent applications with elevated privileges 282from opening files which are even unsafe to open with 283.Dv O_RDONLY , 284such as device nodes. 285.Pp 286.Dv O_CLOEXEC 287may be used to set 288.Dv FD_CLOEXEC 289flag for the newly returned file descriptor. 290.Pp 291.Dv O_VERIFY 292may be used to indicate to the kernel that the contents of the file should 293be verified before allowing the open to proceed. 294The details of what 295.Dq verified 296means is implementation specific. 297The run-time linker (rtld) uses this flag to ensure shared objects have 298been verified before operating on them. 299.Pp 300.Dv O_RESOLVE_BENEATH 301returns 302.Er ENOTCAPABLE 303if any intermediate component of the specified relative path does not 304reside in the directory hierarchy beneath the starting directory. 305Absolute paths or even the temporal escape from beneath of the starting 306directory is not allowed. 307.Pp 308When 309.Fa fd 310is opened with 311.Dv O_SEARCH , 312execute permissions are checked at open time. 313The 314.Fa fd 315may not be used for any read operations like 316.Xr getdirentries 2 . 317The primary use for this descriptor will be as the lookup descriptor for the 318.Fn *at 319family of functions. 320.Pp 321.Dv O_PATH 322returns a file descriptor that can be used as a directory file descriptor for 323.Xr openat 2 324and other system calls taking a file descriptor argument, like 325.Xr fstatat 2 326and others. 327The other functionality of the returned file descriptor is limited to 328the descriptor-level operations. 329It can be used for 330.Bl -tag -width SCM_RIGHTS -offset indent -compact 331.It Xr fcntl 2 332but advisory locking is not allowed 333.It Xr dup 2 334.It Xr close 2 335.It Xr fstat 2 336.It Xr fexecve 2 337requires that 338.Dv O_EXEC 339was also specified at open time 340.It Dv SCM_RIGHTS 341can be passed over a 342.Xr unix 4 343socket using a 344.Dv SCM_RIGHTS 345message 346.It Xr kqueue 2 347using for 348.Dv EVFILT_VNODE 349.El 350But operations like 351.Xr read 2 , 352.Xr ftruncate 2 , 353and any other that operate on file and not on file descriptor (except 354.Xr fstat 2 ), 355are not allowed. 356File opened with the 357.Dv O_PATH 358flag does not prevent non-forced unmount of the volume it belongs to. 359.Pp 360A file descriptor created with the 361.Dv O_PATH 362flag can be opened into normal (operable) file descriptor by 363specifying it as the 364.Fa fd 365argument to 366.Fn openat 367with empty 368.Fa path 369and flag 370.Dv O_EMPTY_PATH . 371Such an open behaves as if the current path of the file referenced by 372.Fa fd 373is passed, except that the path walk permissions are not checked. 374See also the description of 375.Dv AT_EMPTY_PATH 376flag for 377.Xr fstatat 2 378and related syscalls. 379.Pp 380If successful, 381.Fn open 382returns a non-negative integer, termed a file descriptor. 383It returns \-1 on failure. 384The file pointer used to mark the current position within the 385file is set to the beginning of the file. 386.Pp 387If a sleeping open of a device node from 388.Xr devfs 5 389is interrupted by a signal, the call always fails with 390.Er EINTR , 391even if the 392.Dv SA_RESTART 393flag is set for the signal. 394A sleeping open of a fifo (see 395.Xr mkfifo 2 ) 396is restarted as normal. 397.Pp 398When a new file is created it is given the group of the directory 399which contains it. 400.Pp 401Unless 402.Dv O_CLOEXEC 403flag was specified, 404the new descriptor is set to remain open across 405.Xr execve 2 406system calls; see 407.Xr close 2 , 408.Xr fcntl 2 409and 410.Dv O_CLOEXEC 411description. 412.Pp 413The system imposes a limit on the number of file descriptors 414open simultaneously by one process. 415The 416.Xr getdtablesize 2 417system call returns the current system limit. 418.Sh RETURN VALUES 419If successful, 420.Fn open 421and 422.Fn openat 423return a non-negative integer, termed a file descriptor. 424They return \-1 on failure, and set 425.Va errno 426to indicate the error. 427.Sh ERRORS 428The named file is opened unless: 429.Bl -tag -width Er 430.It Bq Er ENOTDIR 431A component of the path prefix is not a directory. 432.It Bq Er ENAMETOOLONG 433A component of a pathname exceeded 255 characters, 434or an entire path name exceeded 1023 characters. 435.It Bq Er ENOENT 436.Dv O_CREAT 437is not set and the named file does not exist. 438.It Bq Er ENOENT 439A component of the path name that must exist does not exist. 440.It Bq Er EACCES 441Search permission is denied for a component of the path prefix. 442.It Bq Er EACCES 443The required permissions (for reading and/or writing) 444are denied for the given flags. 445.It Bq Er EACCES 446.Dv O_TRUNC 447is specified and write permission is denied. 448.It Bq Er EACCES 449.Dv O_CREAT 450is specified, 451the file does not exist, 452and the directory in which it is to be created 453does not permit writing. 454.It Bq Er EPERM 455.Dv O_CREAT 456is specified, the file does not exist, and the directory in which it is to be 457created has its immutable flag set, see the 458.Xr chflags 2 459manual page for more information. 460.It Bq Er EPERM 461The named file has its immutable flag set and the file is to be modified. 462.It Bq Er EPERM 463The named file has its append-only flag set, the file is to be modified, and 464.Dv O_TRUNC 465is specified or 466.Dv O_APPEND 467is not specified. 468.It Bq Er ELOOP 469Too many symbolic links were encountered in translating the pathname. 470.It Bq Er EISDIR 471The named file is a directory, and the arguments specify 472it is to be modified. 473.It Bq Er EISDIR 474The named file is a directory, and the flags specified 475.Dv O_CREAT 476without 477.Dv O_DIRECTORY . 478.It Bq Er EROFS 479The named file resides on a read-only file system, 480and the file is to be modified. 481.It Bq Er EROFS 482.Dv O_CREAT 483is specified and the named file would reside on a read-only file system. 484.It Bq Er EMFILE 485The process has already reached its limit for open file descriptors. 486.It Bq Er ENFILE 487The system file table is full. 488.It Bq Er EMLINK 489.Dv O_NOFOLLOW 490was specified and the target is a symbolic link. 491.It Bq Er ENXIO 492The named file is a character special or block 493special file, and the device associated with this special file 494does not exist. 495.It Bq Er ENXIO 496.Dv O_NONBLOCK 497is set, the named file is a fifo, 498.Dv O_WRONLY 499is set, and no process has the file open for reading. 500.It Bq Er EINTR 501The 502.Fn open 503operation was interrupted by a signal. 504.It Bq Er EOPNOTSUPP 505.Dv O_SHLOCK 506or 507.Dv O_EXLOCK 508is specified but the underlying file system does not support locking. 509.It Bq Er EOPNOTSUPP 510The named file is a special file mounted through a file system that 511does not support access to it (e.g.\& NFS). 512.It Bq Er EWOULDBLOCK 513.Dv O_NONBLOCK 514and one of 515.Dv O_SHLOCK 516or 517.Dv O_EXLOCK 518is specified and the file is locked. 519.It Bq Er ENOSPC 520.Dv O_CREAT 521is specified, 522the file does not exist, 523and the directory in which the entry for the new file is being placed 524cannot be extended because there is no space left on the file 525system containing the directory. 526.It Bq Er ENOSPC 527.Dv O_CREAT 528is specified, 529the file does not exist, 530and there are no free inodes on the file system on which the 531file is being created. 532.It Bq Er EDQUOT 533.Dv O_CREAT 534is specified, 535the file does not exist, 536and the directory in which the entry for the new file 537is being placed cannot be extended because the 538user's quota of disk blocks on the file system 539containing the directory has been exhausted. 540.It Bq Er EDQUOT 541.Dv O_CREAT 542is specified, 543the file does not exist, 544and the user's quota of inodes on the file system on 545which the file is being created has been exhausted. 546.It Bq Er EIO 547An I/O error occurred while making the directory entry or 548allocating the inode for 549.Dv O_CREAT . 550.It Bq Er EINTEGRITY 551Corrupted data was detected while reading from the file system. 552.It Bq Er ETXTBSY 553The file is a pure procedure (shared text) file that is being 554executed and the 555.Fn open 556system call requests write access. 557.It Bq Er EFAULT 558The 559.Fa path 560argument 561points outside the process's allocated address space. 562.It Bq Er EEXIST 563.Dv O_CREAT 564and 565.Dv O_EXCL 566were specified and the file exists. 567.It Bq Er EOPNOTSUPP 568An attempt was made to open a socket (not currently implemented). 569.It Bq Er EINVAL 570An attempt was made to open a descriptor with an illegal combination 571of 572.Dv O_RDONLY , 573.Dv O_WRONLY , 574or 575.Dv O_RDWR , 576and 577.Dv O_EXEC 578or 579.Dv O_SEARCH . 580.It Bq Er EINVAL 581The 582.Dv O_RESOLVE_BENEATH 583flag is specified and 584.Dv path 585is absolute. 586.It Bq Er EBADF 587The 588.Fa path 589argument does not specify an absolute path and the 590.Fa fd 591argument is 592neither 593.Dv AT_FDCWD 594nor a valid file descriptor open for searching. 595.It Bq Er ENOTDIR 596The 597.Fa path 598argument is not an absolute path and 599.Fa fd 600is neither 601.Dv AT_FDCWD 602nor a file descriptor associated with a directory. 603.It Bq Er ENOTDIR 604.Dv O_DIRECTORY 605is specified and the file is not a directory. 606.It Bq Er ECAPMODE 607.Dv AT_FDCWD 608is specified and the process is in capability mode. 609.It Bq Er ECAPMODE 610.Fn open 611was called and the process is in capability mode. 612.It Bq Er ENOTCAPABLE 613.Fa path 614is an absolute path, 615or contained a ".." component leading to a 616directory outside of the directory hierarchy specified by 617.Fa fd , 618and the process is in capability mode. 619.It Bq Er ENOTCAPABLE 620The 621.Dv O_RESOLVE_BENEATH 622flag was provided, and the relative 623.Fa path 624escapes the 625.Ar fd 626directory. 627.El 628.Sh SEE ALSO 629.Xr chmod 2 , 630.Xr close 2 , 631.Xr dup 2 , 632.Xr fexecve 2 , 633.Xr fhopen 2 , 634.Xr getdtablesize 2 , 635.Xr getfh 2 , 636.Xr lgetfh 2 , 637.Xr lseek 2 , 638.Xr read 2 , 639.Xr umask 2 , 640.Xr write 2 , 641.Xr fopen 3 , 642.Xr capsicum 4 643.Sh STANDARDS 644These functions are specified by 645.St -p1003.1-2008 . 646.Fx 647sets 648.Va errno 649to 650.Er EMLINK instead of 651.Er ELOOP 652as specified by 653.Tn POSIX 654when 655.Dv O_NOFOLLOW 656is set in flags and the final component of pathname is a symbolic link 657to distinguish it from the case of too many symbolic link traversals 658in one of its non-final components. 659.Sh HISTORY 660The 661.Fn open 662function appeared in 663.At v1 . 664The 665.Fn openat 666function was introduced in 667.Fx 8.0 . 668.Dv O_DSYNC 669appeared in 13.0. 670.Sh BUGS 671The Open Group Extended API Set 2 specification requires that the test 672for whether 673.Fa fd 674is searchable is based on whether 675.Fa fd 676is open for searching, not whether the underlying directory currently 677permits searches. 678The present implementation of the 679.Fa openat 680checks the current permissions of directory instead. 681.Pp 682The 683.Fa mode 684argument is variadic and may result in different calling conventions 685than might otherwise be expected. 686