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 October 9, 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 readlinkat(2) -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.It Xr readlinkat 2 350.El 351But operations like 352.Xr read 2 , 353.Xr ftruncate 2 , 354and any other that operate on file and not on file descriptor (except 355.Xr fstat 2 ), 356are not allowed. 357File opened with the 358.Dv O_PATH 359flag does not prevent non-forced unmount of the volume it belongs to. 360.Pp 361A file descriptor created with the 362.Dv O_PATH 363flag can be opened into normal (operable) file descriptor by 364specifying it as the 365.Fa fd 366argument to 367.Fn openat 368with empty 369.Fa path 370and flag 371.Dv O_EMPTY_PATH . 372Such an open behaves as if the current path of the file referenced by 373.Fa fd 374is passed, except that the path walk permissions are not checked. 375See also the description of 376.Dv AT_EMPTY_PATH 377flag for 378.Xr fstatat 2 379and related syscalls. 380.Pp 381If successful, 382.Fn open 383returns a non-negative integer, termed a file descriptor. 384It returns \-1 on failure. 385The file pointer used to mark the current position within the 386file is set to the beginning of the file. 387.Pp 388If a sleeping open of a device node from 389.Xr devfs 5 390is interrupted by a signal, the call always fails with 391.Er EINTR , 392even if the 393.Dv SA_RESTART 394flag is set for the signal. 395A sleeping open of a fifo (see 396.Xr mkfifo 2 ) 397is restarted as normal. 398.Pp 399When a new file is created it is given the group of the directory 400which contains it. 401.Pp 402Unless 403.Dv O_CLOEXEC 404flag was specified, 405the new descriptor is set to remain open across 406.Xr execve 2 407system calls; see 408.Xr close 2 , 409.Xr fcntl 2 410and 411.Dv O_CLOEXEC 412description. 413.Pp 414The system imposes a limit on the number of file descriptors 415open simultaneously by one process. 416The 417.Xr getdtablesize 2 418system call returns the current system limit. 419.Sh RETURN VALUES 420If successful, 421.Fn open 422and 423.Fn openat 424return a non-negative integer, termed a file descriptor. 425They return \-1 on failure, and set 426.Va errno 427to indicate the error. 428.Sh ERRORS 429The named file is opened unless: 430.Bl -tag -width Er 431.It Bq Er ENOTDIR 432A component of the path prefix is not a directory. 433.It Bq Er ENAMETOOLONG 434A component of a pathname exceeded 255 characters, 435or an entire path name exceeded 1023 characters. 436.It Bq Er ENOENT 437.Dv O_CREAT 438is not set and the named file does not exist. 439.It Bq Er ENOENT 440A component of the path name that must exist does not exist. 441.It Bq Er EACCES 442Search permission is denied for a component of the path prefix. 443.It Bq Er EACCES 444The required permissions (for reading and/or writing) 445are denied for the given flags. 446.It Bq Er EACCES 447.Dv O_TRUNC 448is specified and write permission is denied. 449.It Bq Er EACCES 450.Dv O_CREAT 451is specified, 452the file does not exist, 453and the directory in which it is to be created 454does not permit writing. 455.It Bq Er EPERM 456.Dv O_CREAT 457is specified, the file does not exist, and the directory in which it is to be 458created has its immutable flag set, see the 459.Xr chflags 2 460manual page for more information. 461.It Bq Er EPERM 462The named file has its immutable flag set and the file is to be modified. 463.It Bq Er EPERM 464The named file has its append-only flag set, the file is to be modified, and 465.Dv O_TRUNC 466is specified or 467.Dv O_APPEND 468is not specified. 469.It Bq Er ELOOP 470Too many symbolic links were encountered in translating the pathname. 471.It Bq Er EISDIR 472The named file is a directory, and the arguments specify 473it is to be modified. 474.It Bq Er EISDIR 475The named file is a directory, and the flags specified 476.Dv O_CREAT 477without 478.Dv O_DIRECTORY . 479.It Bq Er EROFS 480The named file resides on a read-only file system, 481and the file is to be modified. 482.It Bq Er EROFS 483.Dv O_CREAT 484is specified and the named file would reside on a read-only file system. 485.It Bq Er EMFILE 486The process has already reached its limit for open file descriptors. 487.It Bq Er ENFILE 488The system file table is full. 489.It Bq Er EMLINK 490.Dv O_NOFOLLOW 491was specified and the target is a symbolic link. 492.It Bq Er ENXIO 493The named file is a character special or block 494special file, and the device associated with this special file 495does not exist. 496.It Bq Er ENXIO 497.Dv O_NONBLOCK 498is set, the named file is a fifo, 499.Dv O_WRONLY 500is set, and no process has the file open for reading. 501.It Bq Er EINTR 502The 503.Fn open 504operation was interrupted by a signal. 505.It Bq Er EOPNOTSUPP 506.Dv O_SHLOCK 507or 508.Dv O_EXLOCK 509is specified but the underlying file system does not support locking. 510.It Bq Er EOPNOTSUPP 511The named file is a special file mounted through a file system that 512does not support access to it (e.g.\& NFS). 513.It Bq Er EWOULDBLOCK 514.Dv O_NONBLOCK 515and one of 516.Dv O_SHLOCK 517or 518.Dv O_EXLOCK 519is specified and the file is locked. 520.It Bq Er ENOSPC 521.Dv O_CREAT 522is specified, 523the file does not exist, 524and the directory in which the entry for the new file is being placed 525cannot be extended because there is no space left on the file 526system containing the directory. 527.It Bq Er ENOSPC 528.Dv O_CREAT 529is specified, 530the file does not exist, 531and there are no free inodes on the file system on which the 532file is being created. 533.It Bq Er EDQUOT 534.Dv O_CREAT 535is specified, 536the file does not exist, 537and the directory in which the entry for the new file 538is being placed cannot be extended because the 539user's quota of disk blocks on the file system 540containing the directory has been exhausted. 541.It Bq Er EDQUOT 542.Dv O_CREAT 543is specified, 544the file does not exist, 545and the user's quota of inodes on the file system on 546which the file is being created has been exhausted. 547.It Bq Er EIO 548An I/O error occurred while making the directory entry or 549allocating the inode for 550.Dv O_CREAT . 551.It Bq Er EINTEGRITY 552Corrupted data was detected while reading from the file system. 553.It Bq Er ETXTBSY 554The file is a pure procedure (shared text) file that is being 555executed and the 556.Fn open 557system call requests write access. 558.It Bq Er EFAULT 559The 560.Fa path 561argument 562points outside the process's allocated address space. 563.It Bq Er EEXIST 564.Dv O_CREAT 565and 566.Dv O_EXCL 567were specified and the file exists. 568.It Bq Er EOPNOTSUPP 569An attempt was made to open a socket (not currently implemented). 570.It Bq Er EINVAL 571An attempt was made to open a descriptor with an illegal combination 572of 573.Dv O_RDONLY , 574.Dv O_WRONLY , 575or 576.Dv O_RDWR , 577and 578.Dv O_EXEC 579or 580.Dv O_SEARCH . 581.It Bq Er EINVAL 582The 583.Dv O_RESOLVE_BENEATH 584flag is specified and 585.Dv path 586is absolute. 587.It Bq Er EBADF 588The 589.Fa path 590argument does not specify an absolute path and the 591.Fa fd 592argument is 593neither 594.Dv AT_FDCWD 595nor a valid file descriptor open for searching. 596.It Bq Er ENOTDIR 597The 598.Fa path 599argument is not an absolute path and 600.Fa fd 601is neither 602.Dv AT_FDCWD 603nor a file descriptor associated with a directory. 604.It Bq Er ENOTDIR 605.Dv O_DIRECTORY 606is specified and the file is not a directory. 607.It Bq Er ECAPMODE 608.Dv AT_FDCWD 609is specified and the process is in capability mode. 610.It Bq Er ECAPMODE 611.Fn open 612was called and the process is in capability mode. 613.It Bq Er ENOTCAPABLE 614.Fa path 615is an absolute path, 616or contained a ".." component leading to a 617directory outside of the directory hierarchy specified by 618.Fa fd , 619and the process is in capability mode. 620.It Bq Er ENOTCAPABLE 621The 622.Dv O_RESOLVE_BENEATH 623flag was provided, and the relative 624.Fa path 625escapes the 626.Ar fd 627directory. 628.El 629.Sh SEE ALSO 630.Xr chmod 2 , 631.Xr close 2 , 632.Xr dup 2 , 633.Xr fexecve 2 , 634.Xr fhopen 2 , 635.Xr getdtablesize 2 , 636.Xr getfh 2 , 637.Xr lgetfh 2 , 638.Xr lseek 2 , 639.Xr read 2 , 640.Xr umask 2 , 641.Xr write 2 , 642.Xr fopen 3 , 643.Xr capsicum 4 644.Sh STANDARDS 645These functions are specified by 646.St -p1003.1-2008 . 647.Fx 648sets 649.Va errno 650to 651.Er EMLINK instead of 652.Er ELOOP 653as specified by 654.Tn POSIX 655when 656.Dv O_NOFOLLOW 657is set in flags and the final component of pathname is a symbolic link 658to distinguish it from the case of too many symbolic link traversals 659in one of its non-final components. 660.Sh HISTORY 661The 662.Fn open 663function appeared in 664.At v1 . 665The 666.Fn openat 667function was introduced in 668.Fx 8.0 . 669.Dv O_DSYNC 670appeared in 13.0. 671.Sh BUGS 672The Open Group Extended API Set 2 specification requires that the test 673for whether 674.Fa fd 675is searchable is based on whether 676.Fa fd 677is open for searching, not whether the underlying directory currently 678permits searches. 679The present implementation of the 680.Fa openat 681checks the current permissions of directory instead. 682.Pp 683The 684.Fa mode 685argument is variadic and may result in different calling conventions 686than might otherwise be expected. 687