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