1.\" 2.\" Copyright (c) 2010 Apple Inc. All rights reserved. 3.\" 4.\" @APPLE_LICENSE_HEADER_START@ 5.\" 6.\" This file contains Original Code and/or Modifications of Original Code 7.\" as defined in and that are subject to the Apple Public Source License 8.\" Version 2.0 (the 'License'). You may not use this file except in 9.\" compliance with the License. Please obtain a copy of the License at 10.\" http://www.opensource.apple.com/apsl/ and read it before using this 11.\" file. 12.\" 13.\" The Original Code and all software distributed under the License are 14.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18.\" Please see the License for the specific language governing rights and 19.\" limitations under the License. 20.\" 21.\" @APPLE_LICENSE_HEADER_END@ 22.\" 23.\" 24.\" $NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd Exp $ 25.\" 26.\" Copyright (c) 1980, 1991, 1993 27.\" The Regents of the University of California. All rights reserved. 28.\" 29.\" Redistribution and use in source and binary forms, with or without 30.\" modification, are permitted provided that the following conditions 31.\" are met: 32.\" 1. Redistributions of source code must retain the above copyright 33.\" notice, this list of conditions and the following disclaimer. 34.\" 2. Redistributions in binary form must reproduce the above copyright 35.\" notice, this list of conditions and the following disclaimer in the 36.\" documentation and/or other materials provided with the distribution. 37.\" 3. All advertising materials mentioning features or use of this software 38.\" must display the following acknowledgement: 39.\" This product includes software developed by the University of 40.\" California, Berkeley and its contributors. 41.\" 4. Neither the name of the University nor the names of its contributors 42.\" may be used to endorse or promote products derived from this software 43.\" without specific prior written permission. 44.\" 45.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 46.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 47.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 48.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 49.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 50.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 51.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 52.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 53.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 54.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 55.\" SUCH DAMAGE. 56.\" 57.\" @(#)open.2 8.2 (Berkeley) 11/16/93 58.\" 59.Dd June 3, 2021 60.Dt OPEN 2 61.Os BSD 4 62.Sh NAME 63.Nm open , openat 64.Nd open or create a file for reading or writing 65.Sh SYNOPSIS 66.\" OH??? .Fd #include <sys/stat.h> 67.Fd #include <fcntl.h> 68.Ft int 69.Fo open 70.Fa "const char *path" 71.Fa "int oflag" 72.Fa "..." 73.Fc 74.Ft int 75.Fn openat "int fd" "const char *path" "int oflag" "..." 76.Sh DESCRIPTION 77The file name specified by 78.Fa path 79is opened 80for reading and/or writing, 81as specified by the argument 82.Fa oflag ; 83the file descriptor is returned to the calling process. 84.Pp 85The 86.Fa oflag 87argument may indicate that the file is to be 88created if it does not exist (by specifying the 89.Dv O_CREAT 90flag). In this case, 91.Fn open 92and 93.Fn openat 94require an additional argument 95.Fa "mode_t mode" ; 96the file is created with mode 97.Fa mode 98as described in 99.Xr chmod 2 100and modified by the process' umask value (see 101.Xr umask 2 ) . 102.Pp 103The 104.Fn openat 105function is equivalent to the 106.Fn open 107function except in the case where the 108.Fa path 109specifies a relative path. 110In this case the file to be opened is determined relative to the directory 111associated with the file descriptor 112.Fa fd 113instead of the current working directory. 114The 115.Fa oflag 116argument and the optional fourth argument correspond exactly to 117the arguments for 118.Fn open . 119If 120.Fn openat 121is passed the special value 122.Dv AT_FDCWD 123in the 124.Fa fd 125argument, the current working directory is used 126and the behavior is identical to a call to 127.Fn open . 128.Pp 129The flags specified 130for the 131.Fa oflag 132argument must include exactly one of the following file access modes: 133.Pp 134.Bd -literal -offset indent -compact 135O_RDONLY open for reading only 136O_WRONLY open for writing only 137O_RDWR open for reading and writing 138O_SEARCH open directory for searching 139O_EXEC open for execute only 140.Ed 141.Pp 142In addition any combination of the following values can be 143.Em or Ns 'ed in 144.Fa oflag: 145.Pp 146.Bd -literal -offset indent -compact 147O_NONBLOCK do not block on open or for data to become available 148O_APPEND append on each write 149O_CREAT create file if it does not exist 150O_TRUNC truncate size to 0 151O_EXCL error if O_CREAT and the file exists 152O_SHLOCK atomically obtain a shared lock 153O_EXLOCK atomically obtain an exclusive lock 154O_DIRECTORY restrict open to a directory 155O_NOFOLLOW do not follow symlinks 156O_SYMLINK allow open of symlinks 157O_EVTONLY descriptor requested for event notifications only 158O_CLOEXEC mark as close-on-exec 159O_NOFOLLOW_ANY do not follow symlinks in the entire path 160O_RESOLVE_BENEATH path resolution must not escape the directory associated with the file descriptor 161O_UNIQUE ensure a file is opened only if it has a single hard link 162.Ed 163.Pp 164Opening a file with 165.Dv O_APPEND 166set causes each write on the file to be appended to the end. If 167.Dv O_TRUNC 168is specified and the 169file exists, the file is truncated to zero length. 170If 171.Dv O_EXCL 172is set with 173.Dv O_CREAT 174and the file already 175exists, 176.Fn open 177returns an error. 178This may be used to implement a simple exclusive-access locking mechanism. 179If 180.Dv O_EXCL 181is set with 182.Dv O_CREAT 183and the last component of the pathname is a symbolic link, 184.Fn open 185will fail even if the symbolic link points to a non-existent name. 186.Pp 187If the 188.Dv O_NONBLOCK 189flag is specified, do not wait for the device or file 190to be ready or available. If the 191.Fn open 192call would result 193in the process being blocked for some reason 194(e.g., waiting for carrier on a dialup line), 195.Fn open 196returns immediately. 197This flag also has the effect of making all subsequent I/O 198on the open file non-blocking. 199.Pp 200When opening a file, a lock with 201.Xr flock 2 202semantics can be obtained by setting 203.Dv O_SHLOCK 204for a shared lock, or 205.Dv O_EXLOCK 206for an exclusive lock. 207If creating a file with 208.Dv O_CREAT , 209the request for the lock will never fail 210(provided that the underlying filesystem supports locking). 211.Pp 212If 213.Dv O_DIRECTORY 214is used in the mask and the target file passed to 215.Fn open 216is not a directory then the 217.Fn open 218will fail. 219.Pp 220If 221.Dv O_NOFOLLOW 222is used in the mask and the target file passed to 223.Fn open 224is a symbolic link then the 225.Fn open 226will fail. 227.Pp 228If 229.Dv O_SYMLINK 230is used in the mask and the target file passed to 231.Fn open 232is a symbolic link then the 233.Fn open 234will be for the symbolic link itself, not what it links to. 235.Pp 236The 237.Dv O_EVTONLY 238flag is only intended for monitoring a file for changes (e.g. kqueue). Note: when 239this flag is used, the opened file will not prevent an unmount 240of the volume that contains the file. 241.Pp 242The 243.Dv O_CLOEXEC 244flag causes the file descriptor to be marked as close-on-exec, 245setting the 246.Dv FD_CLOEXEC 247flag. The state of the file descriptor flags can be inspected 248using the F_GETFD fcntl. See 249.Xr fcntl 2 . 250.Pp 251If 252.Dv O_NOFOLLOW_ANY 253is used in the mask and any component of the path passed to 254.Fn open 255is a symbolic link then the 256.Fn open 257will fail. 258.Pp 259If 260.Dv O_RESOLVE_BENEATH 261is used in the mask and the specified path resolution escapes the directory associated with the 262.Fa fd 263then the 264.Fn openat 265will fail. 266.Pp 267If 268.Dv O_UNIQUE 269is used in the mask, the open operation will fail if the file has more than one hard link pointing to it. 270The operation succeeds only if the file is guaranteed to be uniquely accessible through the provided pathname. 271.Pp 272If successful, 273.Fn open 274returns a non-negative integer, termed a file descriptor. 275It returns -1 on failure. 276The file pointer (used to mark the current position within the file) 277is set to the beginning of the file. 278.Pp 279When a new file is created, 280it is given the group of the directory which contains it. 281.Pp 282The new descriptor is set to remain open across 283.Xr execve 284system calls; see 285.Xr close 2 286and 287.Xr fcntl 2 . 288.Pp 289The system imposes a limit on the number of file descriptors 290that can be held open simultaneously by one process. 291.Pp 292A file's metadata can be updated even if the file was opened in read-only mode. 293.Xr Getdtablesize 2 294returns the current system limit. 295.Sh RETURN VALUES 296If successful, 297.Fn open 298returns a non-negative integer, termed a file descriptor. 299It returns -1 on failure, and sets 300.Va errno 301to indicate the error. 302.Sh ERRORS 303The named file is opened unless: 304.Bl -tag -width Er 305.\" =========== 306.It Bq Er EACCES 307Search permission is denied for a component of the path prefix. 308.\" =========== 309.It Bq Er EACCES 310The required permissions (for reading and/or writing or search or executing) 311are denied for the given flags. 312.\" =========== 313.It Bq Er EACCES 314.Dv O_CREAT 315is specified, 316the file does not exist, 317and the directory in which it is to be created 318does not permit writing. 319.\" =========== 320.It Bq Er EACCES 321.Dv O_TRUNC 322is specified and write permission is denied. 323.\" =========== 324.It Bq Er EAGAIN 325.Fa path 326specifies the slave side of a locked pseudo-terminal device. 327.\" =========== 328.It Bq Er EDQUOT 329.Dv O_CREAT 330is specified, 331the file does not exist, 332and the directory in which the entry for the new file 333is being placed cannot be extended because the 334user's quota of disk blocks on the file system 335containing the directory has been exhausted. 336.\" =========== 337.It Bq Er EDQUOT 338.Dv O_CREAT 339is specified, 340the file does not exist, 341and the user's quota of inodes on the file system 342on which the file is being created has been exhausted. 343.\" =========== 344.It Bq Er EEXIST 345.Dv O_CREAT 346and 347.Dv O_EXCL 348are specified and the file exists. 349.\" =========== 350.It Bq Er EFAULT 351.Fa Path 352points outside the process's allocated address space. 353.\" =========== 354.It Bq Er EINTR 355The 356.Fn open 357operation is interrupted by a signal. 358.\" =========== 359.It Bq Er EINVAL 360The value of 361.Fa oflag 362is not valid. 363.\" =========== 364.It Bq Er EIO 365An I/O error occurs while making the directory entry or 366allocating the inode for 367.Dv O_CREAT . 368.\" =========== 369.It Bq Er EISDIR 370The named file is a directory, and the arguments specify 371that it is to be opened for writing. 372.\" =========== 373.It Bq Er EISDIR 374The named file is a directory, and the arguments specify 375that it is to be opened for executing. 376.\" =========== 377.It Bq Er ELOOP 378Too many symbolic links are encountered in translating the pathname. 379This is taken to be indicative of a looping symbolic link. 380.\" =========== 381.It Bq Er EMFILE 382The process has already reached its limit for open file descriptors. 383.\" =========== 384.It Bq Er ENAMETOOLONG 385A component of a pathname exceeds 386.Dv {NAME_MAX} 387characters, or an entire path name exceeded 388.Dv {PATH_MAX} 389characters. 390.\" =========== 391.It Bq Er ENFILE 392The system file table is full. 393.\" =========== 394.It Bq Er ENOTDIR 395.Dv O_DIRECTORY 396was specified and the target is not a directory. 397.\" =========== 398.It Bq Er ENOTDIR 399.Dv O_SEARCH 400was specified and the target is not a directory. 401.\" =========== 402.It Bq Er ELOOP 403.Dv O_NOFOLLOW 404was specified and the target is a symbolic link. 405.\" =========== 406.\" =========== 407.It Bq Er ELOOP 408.Dv O_NOFOLLOW_ANY 409was specified and and a component of the path is a symbolic link. 410.\" =========== 411.It Bq Er ENOENT 412.Dv O_CREAT 413is not set and the named file does not exist. 414.\" =========== 415.It Bq Er ENOENT 416A component of the path name that must exist does not exist. 417.\" =========== 418.It Bq Er ENOSPC 419.Dv O_CREAT 420is specified, 421the file does not exist, 422and the directory in which the entry for the new file is being placed 423cannot be extended because there is no space left on the file 424system containing the directory. 425.\" =========== 426.It Bq Er ENOSPC 427.Dv O_CREAT 428is specified, 429the file does not exist, 430and there are no free inodes on the file system on which the 431file is being created. 432.\" =========== 433.It Bq Er ENOTDIR 434A component of the path prefix is not a directory. 435.\" =========== 436.It Bq Er EDEADLK 437A component of the pathname refers to a 438.Dq dataless 439directory that requires materialization and the I/O policy of the current 440thread or process disallows dataless directory materialization 441.Po see 442.Xr getiopolicy_np 3 443.Pc . 444.\" =========== 445.It Bq Er ENXIO 446The named file is a character-special or block-special file 447and the device associated with this special file does not exist. 448.\" =========== 449.It Bq Er ENXIO 450O_NONBLOCK and O_WRONLY are set, the file is a FIFO, 451and no process has it open for reading. 452.\" =========== 453.It Bq Er EOPNOTSUPP 454.Dv O_SHLOCK 455or 456.Dv O_EXLOCK 457is specified, but the underlying filesystem does not support locking. 458.\" =========== 459.It Bq Er EOPNOTSUPP 460An attempt is made to open a socket (not currently implemented). 461.\" =========== 462.It Bq Er EOVERFLOW 463The named file is a regular file 464and its size does not fit in an object of type off_t. 465.\" =========== 466.It Bq Er EROFS 467The named file resides on a read-only file system, 468and the file is to be modified. 469.\" =========== 470.It Bq Er ETXTBSY 471The file is a pure procedure (shared text) file that is being 472executed and the 473.Fn open 474call requests write access. 475.It Bq Er EBADF 476The 477.Fa path 478argument does not specify an absolute path and the 479.Fa fd 480argument is 481neither 482.Dv AT_FDCWD 483nor a valid file descriptor open for searching. 484.It Bq Er ENOTDIR 485The 486.Fa path 487argument is not an absolute path and 488.Fa fd 489is neither 490.Dv AT_FDCWD 491nor a file descriptor associated with a directory. 492.It Bq Er EILSEQ 493The filename does not match the encoding rules. 494.It Bq Er EWOULDBLOCK 495O_SHLOCK or O_EXLOCK is specified, but the file is locked and the O_NONBLOCK option was specified. 496.It Bq Er ENOTCAPABLE 497.Fa path 498resolution escapes the directory associated with 499.Fa fd 500and O_RESOLVE_BENEATH option was specified. 501.It Bq Er ENOTCAPABLE 502.Fa path 503has multiple hard links and O_UNIQUE option was specified. 504.El 505.Sh COMPATIBILITY 506.Fn open 507on a terminal device (i.e., /dev/console) 508will now make that device a controlling terminal for the process. 509Use the O_NOCTTY flag to open a terminal device 510without changing your controlling terminal. 511.Sh SEE ALSO 512.Xr chmod 2 , 513.Xr close 2 , 514.Xr dup 2 , 515.Xr getdtablesize 2 , 516.Xr lseek 2 , 517.Xr read 2 , 518.Xr umask 2 , 519.Xr write 2 520.Sh HISTORY 521An 522.Fn open 523function call appeared in 524.At v6 . 525The 526.Fn openat 527function was introduced in OS X 10.10 528