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 January 3, 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_EXCL 235is set with 236.Dv O_CREAT 237and the file already 238exists, 239.Fn open 240fails with 241.Er EEXIST . 242This may be used to 243implement a simple exclusive access locking mechanism. 244If 245.Dv O_EXCL 246is set and the last component of the pathname is 247a symbolic link, 248.Fn open 249will fail even if the symbolic 250link points to a non-existent name. 251.Pp 252If 253.Dv O_NONBLOCK 254is specified and the 255.Fn open 256system call would 257block for some reason (for example, waiting for 258carrier on a dialup line), 259.Fn open 260returns immediately. 261The descriptor remains in non-blocking mode for subsequent operations. 262.Pp 263If 264.Dv O_SYNC 265is used in the mask, all writes will 266immediately and synchronously be written to disk. 267.Dv O_FSYNC 268is an historical synonym for 269.Dv O_SYNC . 270.Pp 271If 272.Dv O_DSYNC 273is used in the mask, all data and metadata required to read the data will be 274synchronously written to disk, but changes to metadata such as file access and 275modification timestamps may be written later. 276.Pp 277If 278.Dv O_NOFOLLOW 279is used in the mask and the target file passed to 280.Fn open 281is a symbolic link then the 282.Fn open 283will fail. 284.Pp 285When opening a file, a lock with 286.Xr flock 2 287semantics can be obtained by setting 288.Dv O_SHLOCK 289for a shared lock, or 290.Dv O_EXLOCK 291for an exclusive lock. 292If creating a file with 293.Dv O_CREAT , 294the request for the lock will never fail 295(provided that the underlying file system supports locking). 296.Pp 297.Dv O_DIRECT 298may be used to minimize or eliminate the cache effects of reading and writing. 299The system will attempt to avoid caching the data you read or write. 300If it cannot avoid caching the data, 301it will minimize the impact the data has on the cache. 302Use of this flag can drastically reduce performance if not used with care. 303The semantics of this flag are filesystem dependent, 304and some filesystems may ignore it entirely. 305.Pp 306.Dv O_NOCTTY 307may be used to ensure the OS does not assign this file as the 308controlling terminal when it opens a tty device. 309This is the default on 310.Fx , 311but is present for 312POSIX 313compatibility. 314The 315.Fn open 316system call will not assign controlling terminals on 317.Fx . 318.Pp 319.Dv O_TTY_INIT 320may be used to ensure the OS restores the terminal attributes when 321initially opening a TTY. 322This is the default on 323.Fx , 324but is present for 325POSIX 326compatibility. 327The initial call to 328.Fn open 329on a TTY will always restore default terminal attributes on 330.Fx . 331.Pp 332.Dv O_DIRECTORY 333may be used to ensure the resulting file descriptor refers to a 334directory. 335This flag can be used to prevent applications with elevated privileges 336from opening files which are even unsafe to open with 337.Dv O_RDONLY , 338such as device nodes. 339.Pp 340.Dv O_CLOEXEC 341may be used to set 342.Dv FD_CLOEXEC 343flag for the newly returned file descriptor. 344.Pp 345.Dv O_VERIFY 346may be used to indicate to the kernel that the contents of the file should 347be verified before allowing the open to proceed. 348The details of what 349.Dq verified 350means is implementation specific. 351The run-time linker (rtld) uses this flag to ensure shared objects have 352been verified before operating on them. 353.Pp 354.Dv O_RESOLVE_BENEATH 355returns 356.Er ENOTCAPABLE 357if any intermediate component of the specified relative path does not 358reside in the directory hierarchy beneath the starting directory. 359Absolute paths or even the temporal escape from beneath of the starting 360directory is not allowed. 361.Pp 362When a directory 363is opened with 364.Dv O_SEARCH , 365execute permissions are checked at open time. 366The returned file descriptor 367may not be used for any read operations like 368.Xr getdirentries 2 . 369The primary use of this descriptor is as the lookup descriptor for the 370.Fn *at 371family of functions. 372If 373.Dv O_SEARCH 374was not requested at open time, then the 375.Fn *at 376functions use the current directory permissions for the directory referenced 377by the descriptor at the time of the 378.Fn *at 379call. 380.Pp 381.Dv O_PATH 382returns a file descriptor that can be used as a directory file descriptor for 383.Fn openat 384and other system calls taking a file descriptor argument, like 385.Xr fstatat 2 386and others. 387The other functionality of the returned file descriptor is limited to 388the following descriptor-level operations: 389.Pp 390.Bl -tag -width __acl_aclcheck_fd -offset indent -compact 391.It Xr fcntl 2 392but advisory locking is not allowed 393.It Xr dup 2 394.It Xr close 2 395.It Xr fstat 2 396.It Xr fexecve 2 397.It Dv SCM_RIGHTS 398can be passed over a 399.Xr unix 4 400socket using a 401.Dv SCM_RIGHTS 402message 403.It Xr kqueue 2 404only with 405.Dv EVFILT_VNODE 406.It Xr readlinkat 2 407.It Xr __acl_get_fd 2 408.It Xr __acl_aclcheck_fd 2 409.El 410.Pp 411Other operations like 412.Xr read 2 , 413.Xr ftruncate 2 , 414and any other that operate on file and not on file descriptor (except 415.Xr fstat 2 ), 416are not allowed. 417.Pp 418A file descriptor created with the 419.Dv O_PATH 420flag can be opened as a normal (operable) file descriptor by 421specifying it as the 422.Fa fd 423argument to 424.Fn openat 425with an empty 426.Fa path 427and the 428.Dv O_EMPTY_PATH 429flag. 430Such an open behaves as if the current path of the file referenced by 431.Fa fd 432is passed, except that path walk permissions are not checked. 433See also the description of 434.Dv AT_EMPTY_PATH 435flag for 436.Xr fstatat 2 437and related syscalls. 438.Pp 439If successful, 440.Fn open 441returns a non-negative integer, termed a file descriptor. 442It returns \-1 on failure. 443The file descriptor value returned is the lowest numbered descriptor 444currently not in use by the process. 445The file pointer used to mark the current position within the 446file is set to the beginning of the file. 447.Pp 448If a sleeping open of a device node from 449.Xr devfs 4 450is interrupted by a signal, the call always fails with 451.Er EINTR , 452even if the 453.Dv SA_RESTART 454flag is set for the signal. 455A sleeping open of a fifo (see 456.Xr mkfifo 2 ) 457is restarted as normal. 458.Pp 459When a new file is created, it is assigned the group of the directory 460which contains it. 461.Pp 462Unless 463.Dv O_CLOEXEC 464flag was specified, 465the new descriptor is set to remain open across 466.Xr execve 2 467system calls; see 468.Xr close 2 , 469.Xr fcntl 2 470and the description of the 471.Dv O_CLOEXEC 472flag. 473.Pp 474The system imposes a limit on the number of file descriptors 475open simultaneously by one process. 476The 477.Xr getdtablesize 2 478system call returns the current system limit. 479.Sh RETURN VALUES 480If successful, 481.Fn open 482and 483.Fn openat 484return a non-negative integer, termed a file descriptor. 485They return \-1 on failure, and set 486.Va errno 487to indicate the error. 488.Sh ERRORS 489The named file is opened unless: 490.Bl -tag -width Er 491.It Bq Er ENOTDIR 492A component of the path prefix is not a directory. 493.It Bq Er ENAMETOOLONG 494A component of a pathname exceeded 255 characters, 495or an entire path name exceeded 1023 characters. 496.It Bq Er ENOENT 497.Dv O_CREAT 498is not set and the named file does not exist. 499.It Bq Er ENOENT 500A component of the path name that must exist does not exist. 501.It Bq Er EACCES 502Search permission is denied for a component of the path prefix. 503.It Bq Er EACCES 504The required permissions (for reading and/or writing) 505are denied for the given flags. 506.It Bq Er EACCES 507.Dv O_TRUNC 508is specified and write permission is denied. 509.It Bq Er EACCES 510.Dv O_CREAT 511is specified, 512the file does not exist, 513and the directory in which it is to be created 514does not permit writing. 515.It Bq Er EPERM 516.Dv O_CREAT 517is specified, the file does not exist, and the directory in which it is to be 518created has its immutable flag set, see the 519.Xr chflags 2 520manual page for more information. 521.It Bq Er EPERM 522The named file has its immutable flag set and the file is to be modified. 523.It Bq Er EPERM 524The named file has its append-only flag set, the file is to be modified, and 525.Dv O_TRUNC 526is specified or 527.Dv O_APPEND 528is not specified. 529.It Bq Er ELOOP 530Too many symbolic links were encountered in translating the pathname. 531.It Bq Er EISDIR 532The named file is a directory, and the arguments specify 533it is to be modified. 534.It Bq Er EISDIR 535The named file is a directory, and the flags specified 536.Dv O_CREAT 537without 538.Dv O_DIRECTORY . 539.It Bq Er EROFS 540The named file resides on a read-only file system, 541and the file is to be modified. 542.It Bq Er EROFS 543.Dv O_CREAT 544is specified and the named file would reside on a read-only file system. 545.It Bq Er EMFILE 546The process has already reached its limit for open file descriptors. 547.It Bq Er ENFILE 548The system file table is full. 549.It Bq Er EMLINK 550.Dv O_NOFOLLOW 551was specified and the target is a symbolic link. 552POSIX 553specifies a different error for this case; see the note in 554.Sx STANDARDS 555below. 556.It Bq Er ENXIO 557The named file is a character special or block 558special file, and the device associated with this special file 559does not exist. 560.It Bq Er ENXIO 561.Dv O_NONBLOCK 562is set, the named file is a fifo, 563.Dv O_WRONLY 564is set, and no process has the file open for reading. 565.It Bq Er EINTR 566The 567.Fn open 568operation was interrupted by a signal. 569.It Bq Er EOPNOTSUPP 570.Dv O_SHLOCK 571or 572.Dv O_EXLOCK 573is specified but the underlying file system does not support locking. 574.It Bq Er EOPNOTSUPP 575The named file is a special file mounted through a file system that 576does not support access to it (for example, NFS). 577.It Bq Er EWOULDBLOCK 578.Dv O_NONBLOCK 579and one of 580.Dv O_SHLOCK 581or 582.Dv O_EXLOCK 583is specified and the file is locked. 584.It Bq Er ENOSPC 585.Dv O_CREAT 586is specified, 587the file does not exist, 588and the directory in which the entry for the new file is being placed 589cannot be extended because there is no space left on the file 590system containing the directory. 591.It Bq Er ENOSPC 592.Dv O_CREAT 593is specified, 594the file does not exist, 595and there are no free inodes on the file system on which the 596file is being created. 597.It Bq Er EDQUOT 598.Dv O_CREAT 599is specified, 600the file does not exist, 601and the directory in which the entry for the new file 602is being placed cannot be extended because the 603user's quota of disk blocks on the file system 604containing the directory has been exhausted. 605.It Bq Er EDQUOT 606.Dv O_CREAT 607is specified, 608the file does not exist, 609and the user's quota of inodes on the file system on 610which the file is being created has been exhausted. 611.It Bq Er EIO 612An I/O error occurred while making the directory entry or 613allocating the inode for 614.Dv O_CREAT . 615.It Bq Er EINTEGRITY 616Corrupted data was detected while reading from the file system. 617.It Bq Er ETXTBSY 618The file is a pure procedure (shared text) file that is being 619executed and the 620.Fn open 621system call requests write access. 622.It Bq Er EFAULT 623The 624.Fa path 625argument 626points outside the process's allocated address space. 627.It Bq Er EEXIST 628.Dv O_CREAT 629and 630.Dv O_EXCL 631were specified and the file exists. 632.It Bq Er EOPNOTSUPP 633An attempt was made to open a socket (not currently implemented). 634.It Bq Er EINVAL 635An attempt was made to open a descriptor with an illegal combination 636of 637.Dv O_RDONLY , 638.Dv O_WRONLY , 639or 640.Dv O_RDWR , 641and 642.Dv O_EXEC 643or 644.Dv O_SEARCH . 645.It Bq Er EINVAL 646.Dv O_CREAT 647is specified, 648and the last component of the 649.Fa path 650argument is invalid on the file system on which the file is being created. 651.It Bq Er EBADF 652The 653.Fa path 654argument does not specify an absolute path and the 655.Fa fd 656argument is 657neither 658.Dv AT_FDCWD 659nor a valid file descriptor open for searching. 660.It Bq Er ENOTDIR 661The 662.Fa path 663argument is not an absolute path and 664.Fa fd 665is neither 666.Dv AT_FDCWD 667nor a file descriptor associated with a directory. 668.It Bq Er ENOTDIR 669.Dv O_DIRECTORY 670is specified and the file is not a directory. 671.It Bq Er ECAPMODE 672.Dv AT_FDCWD 673is specified and the process is in capability mode. 674.It Bq Er ECAPMODE 675.Fn open 676was called and the process is in capability mode. 677.It Bq Er ENOTCAPABLE 678.Fa path 679is an absolute path and the process is in capability mode. 680.It Bq Er ENOTCAPABLE 681.Fa path 682is an absolute path and 683.Dv O_RESOLVE_BENEATH 684is specified. 685.It Bq Er ENOTCAPABLE 686.Fa path 687contains a ".." component leading to a directory outside 688of the directory hierarchy specified by 689.Fa fd 690and the process is in capability mode. 691.It Bq Er ENOTCAPABLE 692.Fa path 693contains a ".." component leading to a directory outside 694of the directory hierarchy specified by 695.Fa fd 696and 697.Dv O_RESOLVE_BENEATH 698is specified. 699.It Bq Er ENOTCAPABLE 700.Fa path 701contains a ".." component, the 702.Dv vfs.lookup_cap_dotdot 703.Xr sysctl 3 704is set, and the process is in capability mode. 705.El 706.Sh SEE ALSO 707.Xr chmod 2 , 708.Xr close 2 , 709.Xr dup 2 , 710.Xr fexecve 2 , 711.Xr fhopen 2 , 712.Xr getdtablesize 2 , 713.Xr getfh 2 , 714.Xr lgetfh 2 , 715.Xr lseek 2 , 716.Xr read 2 , 717.Xr umask 2 , 718.Xr write 2 , 719.Xr fopen 3 , 720.Xr capsicum 4 721.Sh STANDARDS 722These functions are specified by 723.St -p1003.1-2008 . 724.Pp 725.Fx 726sets 727.Va errno 728to 729.Er EMLINK instead of 730.Er ELOOP 731as specified by 732POSIX 733when 734.Dv O_NOFOLLOW 735is set in flags and the final component of pathname is a symbolic link 736to distinguish it from the case of too many symbolic link traversals 737in one of its non-final components. 738.Pp 739The Open Group Extended API Set 2 specification, that introduced the 740.Fn *at 741API, required that the test for whether 742.Fa fd 743is searchable is based on whether 744.Fa fd 745is open for searching, not whether the underlying directory currently 746permits searches. 747The present implementation of the 748.Fa openat 749system call is believed to be compatible with 750.\" .St -p1003.1-2017 , 751.\" XXX: This should be replaced in the future when an appropriate argument to 752.\" the St macro is available: -p1003.1-2017 753.No IEEE Std 1003.1-2008, 2017 Edition ("POSIX.1") , 754which specifies that behavior for 755.Dv O_SEARCH , 756in the absence of the flag the implementation checks the current 757permissions of a directory. 758.Sh HISTORY 759The 760.Fn open 761function appeared in 762.At v1 . 763The 764.Fn openat 765function was introduced in 766.Fx 8.0 . 767.Dv O_DSYNC 768appeared in 13.0. 769.Sh BUGS 770The 771.Fa mode 772argument is variadic and may result in different calling conventions 773than might otherwise be expected. 774