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.Dd February 28, 2025 29.Dt OPEN 2 30.Os 31.Sh NAME 32.Nm open , openat 33.Nd open or create a file for reading, writing or executing 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In fcntl.h 38.Ft int 39.Fn open "const char *path" "int flags" "..." 40.Ft int 41.Fn openat "int fd" "const char *path" "int flags" "..." 42.Sh DESCRIPTION 43The file name specified by 44.Fa path 45is opened 46for either execution or reading and/or writing as specified by the 47argument 48.Fa flags 49and the file descriptor returned to the calling process. 50The 51.Fa flags 52argument may indicate the file is to be 53created if it does not exist (by specifying the 54.Dv O_CREAT 55flag). 56In this case 57.Fn open 58and 59.Fn openat 60require an additional argument 61.Fa "mode_t mode" , 62and the file is created with mode 63.Fa mode 64as described in 65.Xr chmod 2 66and modified by the process' umask value (see 67.Xr umask 2 ) . 68.Pp 69The 70.Fn openat 71function is equivalent to the 72.Fn open 73function except in the case where the 74.Fa path 75specifies a relative path. 76For 77.Fn openat 78and relative 79.Fa path , 80the file to be opened is determined relative to the directory 81associated with the file descriptor 82.Fa fd 83instead of the current working directory. 84The 85.Fa flag 86parameter and the optional fourth parameter correspond exactly to 87the parameters of 88.Fn open . 89If 90.Fn openat 91is passed the special value 92.Dv AT_FDCWD 93in the 94.Fa fd 95parameter, the current working directory is used 96and the behavior is identical to a call to 97.Fn open . 98.Pp 99When 100.Fn openat 101is called with an absolute 102.Fa path , 103it ignores the 104.Fa fd 105argument. 106.Pp 107In 108.Xr capsicum 4 109capability mode, 110.Fn open 111is not permitted. 112The 113.Fa path 114argument to 115.Fn openat 116must be strictly relative to a file descriptor 117.Fa fd ; 118that is, 119.Fa path 120must not be an absolute path and must not contain ".." components 121which cause the path resolution to escape the directory hierarchy 122starting at 123.Fa fd . 124Additionally, no symbolic link in 125.Fa path 126may target absolute path or contain escaping ".." components. 127.Fa fd 128must not be 129.Dv AT_FDCWD . 130.Pp 131If the 132.Dv vfs.lookup_cap_dotdot 133.Xr sysctl 3 134MIB is set to zero, ".." components in the paths, 135used in capability mode, 136are completely disabled. 137If the 138.Dv vfs.lookup_cap_dotdot_nonlocal 139MIB is set to zero, ".." is not allowed if found on non-local filesystem. 140.Pp 141The 142.Fa flags 143are formed by 144.Em or Ns 'ing 145the following values: 146.Pp 147.Bl -tag -width O_RESOLVE_BENEATH 148.It Dv O_RDONLY 149open for reading only 150.It Dv O_WRONLY 151open for writing only 152.It Dv O_RDWR 153open for reading and writing 154.It Dv O_EXEC 155open for execute only 156.It Dv O_SEARCH 157open for search only 158(an alias for 159.Dv O_EXEC 160typically used with 161.Dv O_DIRECTORY ) 162.It Dv O_NONBLOCK 163do not block on open 164.It Dv O_APPEND 165set file pointer to the end of the file before each write 166.It Dv O_CREAT 167create file if it does not exist 168.It Dv O_TRUNC 169truncate size to 0 170.It Dv O_EXCL 171fail if 172.Dv O_CREAT 173is set and the file exists 174.It Dv O_SHLOCK 175atomically obtain a shared lock 176.It Dv O_EXLOCK 177atomically obtain an exclusive lock 178.It Dv O_DIRECT 179read and write directly from the backing store 180.It Dv O_FSYNC 181synchronous data and metadata writes 182.Pq historical synonym for Dv O_SYNC 183.It Dv O_SYNC 184synchronous data and metadata writes 185.It Dv O_DSYNC 186synchronous data writes 187.It Dv O_NOFOLLOW 188do not follow symlinks 189.It Dv O_NOCTTY 190ignored 191.It Dv O_TTY_INIT 192ignored 193.It Dv O_DIRECTORY 194error if file is not a directory 195.It Dv O_CLOEXEC 196automatically close file on 197.Xr execve 2 198.It Dv O_VERIFY 199verify the contents of the file with 200.Xr mac_veriexec 4 201.It Dv O_RESOLVE_BENEATH 202.Pq Xr openat 2 only 203path resolution must not cross the 204.Fa fd 205directory 206.It Dv O_PATH 207record only the target path in the opened descriptor 208.It Dv O_EMPTY_PATH 209.Pq Xr openat 2 only 210open file referenced by 211.Fa fd 212if path is empty 213.El 214.Pp 215Exactly one of the flags 216.Dv O_RDONLY , 217.Dv O_WRONLY , 218.Dv O_RDWR , 219or 220.Dv O_EXEC 221must be provided. 222.Pp 223Opening a file with 224.Dv O_APPEND 225set causes each write on the resulting file descriptor 226to be appended to the end of the file. 227.Pp 228If 229.Dv O_TRUNC 230is specified and the 231file exists, the file is truncated to zero length. 232.Pp 233If 234.Dv O_CREAT 235is set, but file already exists, 236this flag has no effect except when 237.Dv O_EXCL 238is set too, in this case 239.Fn open 240fails with 241.Er EEXIST . 242This may be used to 243implement a simple exclusive access locking mechanism. 244In all other cases, the file is created 245and the access permission bits (see 246.Xr chmod 2) 247of the file mode 248are set to the value of the third argument taken as 249.Fa "mode_t mode" 250and passed through the 251.Xr umask 2 . 252This argument does not affect whether the file is opened 253for reading, writing, or for both. 254The open' request for a lock on the file, created with 255.Dv O_CREAT , 256will never fail 257provided that the underlying file system supports locking; 258see also 259.Dv O_SHLOCK 260and 261.Dv O_EXLOCK 262below. 263.Pp 264If 265.Dv O_EXCL 266is set and the last component of the pathname is 267a symbolic link, 268.Fn open 269will fail even if the symbolic 270link points to a non-existent name. 271.Pp 272If 273.Dv O_NONBLOCK 274is specified and the 275.Fn open 276system call would 277block for some reason (for example, waiting for 278carrier on a dialup line), 279.Fn open 280returns immediately. 281The descriptor remains in non-blocking mode for subsequent operations. 282.Pp 283If 284.Dv O_SYNC 285is used in the mask, all writes will 286immediately and synchronously be written to disk. 287.Dv O_FSYNC 288is an historical synonym for 289.Dv O_SYNC . 290.Pp 291If 292.Dv O_DSYNC 293is used in the mask, all data and metadata required to read the data will be 294synchronously written to disk, but changes to metadata such as file access and 295modification timestamps may be written later. 296.Pp 297If 298.Dv O_NOFOLLOW 299is used in the mask and the target file passed to 300.Fn open 301is a symbolic link then the 302.Fn open 303will fail. 304.Pp 305When opening a file, a lock with 306.Xr flock 2 307semantics can be obtained by setting 308.Dv O_SHLOCK 309for a shared lock, or 310.Dv O_EXLOCK 311for an exclusive lock. 312.Pp 313.Dv O_DIRECT 314may be used to minimize or eliminate the cache effects of reading and writing. 315The system will attempt to avoid caching the data you read or write. 316If it cannot avoid caching the data, 317it will minimize the impact the data has on the cache. 318Use of this flag can drastically reduce performance if not used with care. 319The semantics of this flag are filesystem dependent, 320and some filesystems may ignore it entirely. 321.Pp 322.Dv O_NOCTTY 323may be used to ensure the OS does not assign this file as the 324controlling terminal when it opens a tty device. 325This is the default on 326.Fx , 327but is present for 328POSIX 329compatibility. 330The 331.Fn open 332system call will not assign controlling terminals on 333.Fx . 334.Pp 335.Dv O_TTY_INIT 336may be used to ensure the OS restores the terminal attributes when 337initially opening a TTY. 338This is the default on 339.Fx , 340but is present for 341POSIX 342compatibility. 343The initial call to 344.Fn open 345on a TTY will always restore default terminal attributes on 346.Fx . 347.Pp 348.Dv O_DIRECTORY 349may be used to ensure the resulting file descriptor refers to a 350directory. 351This flag can be used to prevent applications with elevated privileges 352from opening files which are even unsafe to open with 353.Dv O_RDONLY , 354such as device nodes. 355.Pp 356.Dv O_CLOEXEC 357may be used to set 358.Dv FD_CLOEXEC 359flag for the newly returned file descriptor. 360.Pp 361.Dv O_VERIFY 362may be used to indicate to the kernel that the contents of the file should 363be verified before allowing the open to proceed. 364The details of what 365.Dq verified 366means is implementation specific. 367The run-time linker (rtld) uses this flag to ensure shared objects have 368been verified before operating on them. 369.Pp 370.Dv O_RESOLVE_BENEATH 371returns 372.Er ENOTCAPABLE 373if any intermediate component of the specified relative path does not 374reside in the directory hierarchy beneath the starting directory. 375Absolute paths or even the temporal escape from beneath of the starting 376directory is not allowed. 377.Pp 378When a directory 379is opened with 380.Dv O_SEARCH , 381execute permissions are checked at open time. 382The returned file descriptor 383may not be used for any read operations like 384.Xr getdirentries 2 . 385The primary use of this descriptor is as the lookup descriptor for the 386.Fn *at 387family of functions. 388If 389.Dv O_SEARCH 390was not requested at open time, then the 391.Fn *at 392functions use the current directory permissions for the directory referenced 393by the descriptor at the time of the 394.Fn *at 395call. 396.Pp 397.Dv O_PATH 398returns a file descriptor that can be used as a directory file descriptor for 399.Fn openat 400and other system calls taking a file descriptor argument, like 401.Xr fstatat 2 402and others. 403The other functionality of the returned file descriptor is limited to 404the following descriptor-level operations: 405.Pp 406.Bl -tag -width __acl_aclcheck_fd -offset indent -compact 407.It Xr fcntl 2 408but advisory locking is not allowed 409.It Xr dup 2 410.It Xr close 2 411.It Xr fstat 2 412.It Xr fstatfs 2 413.It Xr fchdir 2 414.It Xr fchroot 2 415.It Xr fexecve 2 416.It Xr funlinkat 2 417can be passed as the third argument 418.It Dv SCM_RIGHTS 419can be passed over a 420.Xr unix 4 421socket using a 422.Dv SCM_RIGHTS 423message 424.It Xr kqueue 2 425only with 426.Dv EVFILT_VNODE 427.It Xr __acl_get_fd 2 428.It Xr __acl_aclcheck_fd 2 429.It Xr extattr 2 430.It Xr capsicum 4 431can be passed to 432.Fn cap_*_limit 433and 434.Fn cap_*_get 435system calls (such as 436.Xr cap_rights_limit 2 ) . 437.El 438.Pp 439Other operations like 440.Xr read 2 , 441.Xr ftruncate 2 , 442and any other that operate on file and not on file descriptor (except 443.Xr fstat 2 ) , 444are not allowed. 445.Pp 446A file descriptor created with the 447.Dv O_PATH 448flag can be opened as a normal (operable) file descriptor by 449specifying it as the 450.Fa fd 451argument to 452.Fn openat 453with an empty 454.Fa path 455and the 456.Dv O_EMPTY_PATH 457flag. 458Such an open behaves as if the current path of the file referenced by 459.Fa fd 460is passed, except that path walk permissions are not checked. 461See also the description of 462.Dv AT_EMPTY_PATH 463flag for 464.Xr fstatat 2 465and related syscalls. 466.Pp 467Conversely, a file descriptor 468.Dv fd 469referencing a filesystem file can be converted to the 470.Dv O_PATH 471type of descriptor by using the following call 472.Dl opath_fd = openat(fd, \[dq]\[dq], O_EMPTY_PATH | O_PATH); 473.Pp 474If successful, 475.Fn open 476returns a non-negative integer, termed a file descriptor. 477It returns \-1 on failure. 478The file descriptor value returned is the lowest numbered descriptor 479currently not in use by the process. 480The file pointer used to mark the current position within the 481file is set to the beginning of the file. 482.Pp 483If a sleeping open of a device node from 484.Xr devfs 4 485is interrupted by a signal, the call always fails with 486.Er EINTR , 487even if the 488.Dv SA_RESTART 489flag is set for the signal. 490A sleeping open of a fifo (see 491.Xr mkfifo 2 ) 492is restarted as normal. 493.Pp 494When a new file is created, it is assigned the group of the directory 495which contains it. 496.Pp 497Unless 498.Dv O_CLOEXEC 499flag was specified, 500the new descriptor is set to remain open across 501.Xr execve 2 502system calls; see 503.Xr close 2 , 504.Xr fcntl 2 505and the description of the 506.Dv O_CLOEXEC 507flag. 508.Pp 509The system imposes a limit on the number of file descriptors 510open simultaneously by one process. 511The 512.Xr getdtablesize 2 513system call returns the current system limit. 514.Sh RETURN VALUES 515If successful, 516.Fn open 517and 518.Fn openat 519return a non-negative integer, termed a file descriptor. 520They return \-1 on failure, and set 521.Va errno 522to indicate the error. 523.Sh ERRORS 524The named file is opened unless: 525.Bl -tag -width Er 526.It Bq Er ENOTDIR 527A component of the path prefix is not a directory. 528.It Bq Er ENAMETOOLONG 529A component of a pathname exceeded 255 characters, 530or an entire path name exceeded 1023 characters. 531.It Bq Er ENOENT 532.Dv O_CREAT 533is not set and the named file does not exist. 534.It Bq Er ENOENT 535A component of the path name that must exist does not exist. 536.It Bq Er EACCES 537Search permission is denied for a component of the path prefix. 538.It Bq Er EACCES 539The required permissions (for reading and/or writing) 540are denied for the given flags. 541.It Bq Er EACCES 542.Dv O_TRUNC 543is specified and write permission is denied. 544.It Bq Er EACCES 545.Dv O_CREAT 546is specified, 547the file does not exist, 548and the directory in which it is to be created 549does not permit writing. 550.It Bq Er EPERM 551.Dv O_CREAT 552is specified, the file does not exist, and the directory in which it is to be 553created has its immutable flag set, see the 554.Xr chflags 2 555manual page for more information. 556.It Bq Er EPERM 557The named file has its immutable flag set and the file is to be modified. 558.It Bq Er EPERM 559The named file has its append-only flag set, the file is to be modified, and 560.Dv O_TRUNC 561is specified or 562.Dv O_APPEND 563is not specified. 564.It Bq Er ELOOP 565Too many symbolic links were encountered in translating the pathname. 566.It Bq Er EISDIR 567The named file is a directory, and the arguments specify 568it is to be modified. 569.It Bq Er EISDIR 570The named file is a directory, and the flags specified 571.Dv O_CREAT 572without 573.Dv O_DIRECTORY . 574.It Bq Er EROFS 575The named file resides on a read-only file system, 576and the file is to be modified. 577.It Bq Er EROFS 578.Dv O_CREAT 579is specified and the named file would reside on a read-only file system. 580.It Bq Er EMFILE 581The process has already reached its limit for open file descriptors. 582.It Bq Er ENFILE 583The system file table is full. 584.It Bq Er EMLINK 585.Dv O_NOFOLLOW 586was specified and the target is a symbolic link. 587POSIX 588specifies a different error for this case; see the note in 589.Sx STANDARDS 590below. 591.It Bq Er ENXIO 592The named file is a character special or block 593special file, and the device associated with this special file 594does not exist. 595.It Bq Er ENXIO 596.Dv O_NONBLOCK 597is set, the named file is a fifo, 598.Dv O_WRONLY 599is set, and no process has the file open for reading. 600.It Bq Er EINTR 601The 602.Fn open 603operation was interrupted by a signal. 604.It Bq Er EOPNOTSUPP 605.Dv O_SHLOCK 606or 607.Dv O_EXLOCK 608is specified but the underlying file system does not support locking. 609.It Bq Er EOPNOTSUPP 610The named file is a special file mounted through a file system that 611does not support access to it (for example, NFS). 612.It Bq Er EWOULDBLOCK 613.Dv O_NONBLOCK 614and one of 615.Dv O_SHLOCK 616or 617.Dv O_EXLOCK 618is specified and the file is locked. 619.It Bq Er ENOSPC 620.Dv O_CREAT 621is specified, 622the file does not exist, 623and the directory in which the entry for the new file is being placed 624cannot be extended because there is no space left on the file 625system containing the directory. 626.It Bq Er ENOSPC 627.Dv O_CREAT 628is specified, 629the file does not exist, 630and there are no free inodes on the file system on which the 631file is being created. 632.It Bq Er EDQUOT 633.Dv O_CREAT 634is specified, 635the file does not exist, 636and the directory in which the entry for the new file 637is being placed cannot be extended because the 638user's quota of disk blocks on the file system 639containing the directory has been exhausted. 640.It Bq Er EDQUOT 641.Dv O_CREAT 642is specified, 643the file does not exist, 644and the user's quota of inodes on the file system on 645which the file is being created has been exhausted. 646.It Bq Er EIO 647An I/O error occurred while making the directory entry or 648allocating the inode for 649.Dv O_CREAT . 650.It Bq Er EINTEGRITY 651Corrupted data was detected while reading from the file system. 652.It Bq Er ETXTBSY 653The file is a pure procedure (shared text) file that is being 654executed and the 655.Fn open 656system call requests write access. 657.It Bq Er EFAULT 658The 659.Fa path 660argument 661points outside the process's allocated address space. 662.It Bq Er EEXIST 663.Dv O_CREAT 664and 665.Dv O_EXCL 666were specified and the file exists. 667.It Bq Er EOPNOTSUPP 668An attempt was made to open a socket (not currently implemented). 669.It Bq Er EINVAL 670An attempt was made to open a descriptor with an illegal combination 671of 672.Dv O_RDONLY , 673.Dv O_WRONLY , 674or 675.Dv O_RDWR , 676and 677.Dv O_EXEC 678or 679.Dv O_SEARCH . 680.It Bq Er EINVAL 681.Dv O_CREAT 682is specified, 683and the last component of the 684.Fa path 685argument is invalid on the file system on which the file is being created. 686.It Bq Er EBADF 687The 688.Fa path 689argument does not specify an absolute path and the 690.Fa fd 691argument is 692neither 693.Dv AT_FDCWD 694nor a valid file descriptor open for searching. 695.It Bq Er ENOTDIR 696The 697.Fa path 698argument is not an absolute path and 699.Fa fd 700is neither 701.Dv AT_FDCWD 702nor a file descriptor associated with a directory. 703.It Bq Er ENOTDIR 704.Dv O_DIRECTORY 705is specified and the file is not a directory. 706.It Bq Er ECAPMODE 707.Dv AT_FDCWD 708is specified and the process is in capability mode. 709.It Bq Er ECAPMODE 710.Fn open 711was called and the process is in capability mode. 712.It Bq Er ENOTCAPABLE 713.Fa path 714is an absolute path and the process is in capability mode. 715.It Bq Er ENOTCAPABLE 716.Fa path 717is an absolute path and 718.Dv O_RESOLVE_BENEATH 719is specified. 720.It Bq Er ENOTCAPABLE 721.Fa path 722contains a ".." component leading to a directory outside 723of the directory hierarchy specified by 724.Fa fd 725and the process is in capability mode. 726.It Bq Er ENOTCAPABLE 727.Fa path 728contains a ".." component leading to a directory outside 729of the directory hierarchy specified by 730.Fa fd 731and 732.Dv O_RESOLVE_BENEATH 733is specified. 734.It Bq Er ENOTCAPABLE 735.Fa path 736contains a ".." component, the 737.Dv vfs.lookup_cap_dotdot 738.Xr sysctl 3 739is set, and the process is in capability mode. 740.El 741.Sh SEE ALSO 742.Xr chmod 2 , 743.Xr close 2 , 744.Xr dup 2 , 745.Xr fexecve 2 , 746.Xr fhopen 2 , 747.Xr getdtablesize 2 , 748.Xr getfh 2 , 749.Xr lgetfh 2 , 750.Xr lseek 2 , 751.Xr read 2 , 752.Xr umask 2 , 753.Xr write 2 , 754.Xr fopen 3 , 755.Xr capsicum 4 756.Sh STANDARDS 757These functions are specified by 758.St -p1003.1-2008 . 759.Pp 760.Fx 761sets 762.Va errno 763to 764.Er EMLINK instead of 765.Er ELOOP 766as specified by 767POSIX 768when 769.Dv O_NOFOLLOW 770is set in flags and the final component of pathname is a symbolic link 771to distinguish it from the case of too many symbolic link traversals 772in one of its non-final components. 773.Pp 774The Open Group Extended API Set 2 specification, that introduced the 775.Fn *at 776API, required that the test for whether 777.Fa fd 778is searchable is based on whether 779.Fa fd 780is open for searching, not whether the underlying directory currently 781permits searches. 782The present implementation of the 783.Fa openat 784system call is believed to be compatible with 785.\" .St -p1003.1-2017 , 786.\" XXX: This should be replaced in the future when an appropriate argument to 787.\" the St macro is available: -p1003.1-2017 788.No IEEE Std 1003.1-2008, 2017 Edition ("POSIX.1") , 789which specifies that behavior for 790.Dv O_SEARCH , 791in the absence of the flag the implementation checks the current 792permissions of a directory. 793.Sh HISTORY 794The 795.Fn open 796function appeared in 797.At v1 . 798The 799.Fn openat 800function was introduced in 801.Fx 8.0 . 802.Dv O_DSYNC 803appeared in 13.0. 804.Sh BUGS 805The 806.Fa mode 807argument is variadic and may result in different calling conventions 808than might otherwise be expected. 809