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 138.Ed 139.Pp 140In addition any combination of the following values can be 141.Em or Ns 'ed in 142.Fa oflag: 143.Pp 144.Bd -literal -offset indent -compact 145O_NONBLOCK do not block on open or for data to become available 146O_APPEND append on each write 147O_CREAT create file if it does not exist 148O_TRUNC truncate size to 0 149O_EXCL error if O_CREAT and the file exists 150O_SHLOCK atomically obtain a shared lock 151O_EXLOCK atomically obtain an exclusive lock 152O_DIRECTORY restrict open to a directory 153O_NOFOLLOW do not follow symlinks 154O_SYMLINK allow open of symlinks 155O_EVTONLY descriptor requested for event notifications only 156O_CLOEXEC mark as close-on-exec 157O_NOFOLLOW_ANY do not follow symlinks in the entire path. 158.Ed 159.Pp 160Opening a file with 161.Dv O_APPEND 162set causes each write on the file to be appended to the end. If 163.Dv O_TRUNC 164is specified and the 165file exists, the file is truncated to zero length. 166If 167.Dv O_EXCL 168is set with 169.Dv O_CREAT 170and the file already 171exists, 172.Fn open 173returns an error. 174This may be used to implement a simple exclusive-access locking mechanism. 175If 176.Dv O_EXCL 177is set with 178.Dv O_CREAT 179and the last component of the pathname is a symbolic link, 180.Fn open 181will fail even if the symbolic link points to a non-existent name. 182.Pp 183If the 184.Dv O_NONBLOCK 185flag is specified, do not wait for the device or file 186to be ready or available. If the 187.Fn open 188call would result 189in the process being blocked for some reason 190(e.g., waiting for carrier on a dialup line), 191.Fn open 192returns immediately. 193This flag also has the effect of making all subsequent I/O 194on the open file non-blocking. 195.Pp 196When opening a file, a lock with 197.Xr flock 2 198semantics can be obtained by setting 199.Dv O_SHLOCK 200for a shared lock, or 201.Dv O_EXLOCK 202for an exclusive lock. 203If creating a file with 204.Dv O_CREAT , 205the request for the lock will never fail 206(provided that the underlying filesystem supports locking). 207.Pp 208If 209.Dv O_DIRECTORY 210is used in the mask and the target file passed to 211.Fn open 212is not a directory then the 213.Fn open 214will fail. 215.Pp 216If 217.Dv O_NOFOLLOW 218is used in the mask and the target file passed to 219.Fn open 220is a symbolic link then the 221.Fn open 222will fail. 223.Pp 224If 225.Dv O_SYMLINK 226is used in the mask and the target file passed to 227.Fn open 228is a symbolic link then the 229.Fn open 230will be for the symbolic link itself, not what it links to. 231.Pp 232The 233.Dv O_EVTONLY 234flag is only intended for monitoring a file for changes (e.g. kqueue). Note: when 235this flag is used, the opened file will not prevent an unmount 236of the volume that contains the file. 237.Pp 238The 239.Dv O_CLOEXEC 240flag causes the file descriptor to be marked as close-on-exec, 241setting the 242.Dv FD_CLOEXEC 243flag. The state of the file descriptor flags can be inspected 244using the F_GETFD fcntl. See 245.Xr fcntl 2 . 246.Pp 247If 248.Dv O_NOFOLLOW_ANY 249is used in the mask and any component of the path passed to 250.Fn open 251is a symbolic link then the 252.Fn open 253will fail. 254.Pp 255If successful, 256.Fn open 257returns a non-negative integer, termed a file descriptor. 258It returns -1 on failure. 259The file pointer (used to mark the current position within the file) 260is set to the beginning of the file. 261.Pp 262When a new file is created, 263it is given the group of the directory which contains it. 264.Pp 265The new descriptor is set to remain open across 266.Xr execve 267system calls; see 268.Xr close 2 269and 270.Xr fcntl 2 . 271.Pp 272The system imposes a limit on the number of file descriptors 273that can be held open simultaneously by one process. 274.Pp 275A file's metadata can be updated even if the file was opened in read-only mode. 276.Xr Getdtablesize 2 277returns the current system limit. 278.Sh RETURN VALUES 279If successful, 280.Fn open 281returns a non-negative integer, termed a file descriptor. 282It returns -1 on failure, and sets 283.Va errno 284to indicate the error. 285.Sh ERRORS 286The named file is opened unless: 287.Bl -tag -width Er 288.\" =========== 289.It Bq Er EACCES 290Search permission is denied for a component of the path prefix. 291.\" =========== 292.It Bq Er EACCES 293The required permissions (for reading and/or writing) 294are denied for the given flags. 295.\" =========== 296.It Bq Er EACCES 297.Dv O_CREAT 298is specified, 299the file does not exist, 300and the directory in which it is to be created 301does not permit writing. 302.\" =========== 303.It Bq Er EACCES 304.Dv O_TRUNC 305is specified and write permission is denied. 306.\" =========== 307.It Bq Er EAGAIN 308.Fa path 309specifies the slave side of a locked pseudo-terminal device. 310.\" =========== 311.It Bq Er EDQUOT 312.Dv O_CREAT 313is specified, 314the file does not exist, 315and the directory in which the entry for the new file 316is being placed cannot be extended because the 317user's quota of disk blocks on the file system 318containing the directory has been exhausted. 319.\" =========== 320.It Bq Er EDQUOT 321.Dv O_CREAT 322is specified, 323the file does not exist, 324and the user's quota of inodes on the file system 325on which the file is being created has been exhausted. 326.\" =========== 327.It Bq Er EEXIST 328.Dv O_CREAT 329and 330.Dv O_EXCL 331are specified and the file exists. 332.\" =========== 333.It Bq Er EFAULT 334.Fa Path 335points outside the process's allocated address space. 336.\" =========== 337.It Bq Er EINTR 338The 339.Fn open 340operation is interrupted by a signal. 341.\" =========== 342.It Bq Er EINVAL 343The value of 344.Fa oflag 345is not valid. 346.\" =========== 347.It Bq Er EIO 348An I/O error occurs while making the directory entry or 349allocating the inode for 350.Dv O_CREAT . 351.\" =========== 352.It Bq Er EISDIR 353The named file is a directory, and the arguments specify 354that it is to be opened for writing. 355.\" =========== 356.It Bq Er ELOOP 357Too many symbolic links are encountered in translating the pathname. 358This is taken to be indicative of a looping symbolic link. 359.\" =========== 360.It Bq Er EMFILE 361The process has already reached its limit for open file descriptors. 362.\" =========== 363.It Bq Er ENAMETOOLONG 364A component of a pathname exceeds 365.Dv {NAME_MAX} 366characters, or an entire path name exceeded 367.Dv {PATH_MAX} 368characters. 369.\" =========== 370.It Bq Er ENFILE 371The system file table is full. 372.\" =========== 373.It Bq Er ENOTDIR 374.Dv O_DIRECTORY 375was specified and the target is not a directory. 376.\" =========== 377.It Bq Er ELOOP 378.Dv O_NOFOLLOW 379was specified and the target is a symbolic link. 380.\" =========== 381.\" =========== 382.It Bq Er ELOOP 383.Dv O_NOFOLLOW_ANY 384was specified and and a component of the path is a symbolic link. 385.\" =========== 386.It Bq Er ENOENT 387.Dv O_CREAT 388is not set and the named file does not exist. 389.\" =========== 390.It Bq Er ENOENT 391A component of the path name that must exist does not exist. 392.\" =========== 393.It Bq Er ENOSPC 394.Dv O_CREAT 395is specified, 396the file does not exist, 397and the directory in which the entry for the new file is being placed 398cannot be extended because there is no space left on the file 399system containing the directory. 400.\" =========== 401.It Bq Er ENOSPC 402.Dv O_CREAT 403is specified, 404the file does not exist, 405and there are no free inodes on the file system on which the 406file is being created. 407.\" =========== 408.It Bq Er ENOTDIR 409A component of the path prefix is not a directory. 410 .\" =========== 411.It Bq Er EDEADLK 412A component of the pathname refers to a 413.Dq dataless 414directory that requires materialization and the I/O policy of the current 415thread or process disallows dataless directory materialization 416.Po see 417.Xr getiopolicy_np 3 418.Pc . 419.\" =========== 420.It Bq Er ENXIO 421The named file is a character-special or block-special file 422and the device associated with this special file does not exist. 423.\" =========== 424.It Bq Er ENXIO 425O_NONBLOCK and O_WRONLY are set, the file is a FIFO, 426and no process has it open for reading. 427.\" =========== 428.It Bq Er EOPNOTSUPP 429.Dv O_SHLOCK 430or 431.Dv O_EXLOCK 432is specified, but the underlying filesystem does not support locking. 433.\" =========== 434.It Bq Er EOPNOTSUPP 435An attempt is made to open a socket (not currently implemented). 436.\" =========== 437.It Bq Er EOVERFLOW 438The named file is a regular file 439and its size does not fit in an object of type off_t. 440.\" =========== 441.It Bq Er EROFS 442The named file resides on a read-only file system, 443and the file is to be modified. 444.\" =========== 445.It Bq Er ETXTBSY 446The file is a pure procedure (shared text) file that is being 447executed and the 448.Fn open 449call requests write access. 450.It Bq Er EBADF 451The 452.Fa path 453argument does not specify an absolute path and the 454.Fa fd 455argument is 456neither 457.Dv AT_FDCWD 458nor a valid file descriptor open for searching. 459.It Bq Er ENOTDIR 460The 461.Fa path 462argument is not an absolute path and 463.Fa fd 464is neither 465.Dv AT_FDCWD 466nor a file descriptor associated with a directory. 467.It Bq Er EILSEQ 468The filename does not match the encoding rules. 469.El 470.Sh COMPATIBILITY 471.Fn open 472on a terminal device (i.e., /dev/console) 473will now make that device a controlling terminal for the process. 474Use the O_NOCTTY flag to open a terminal device 475without changing your controlling terminal. 476.Sh SEE ALSO 477.Xr chmod 2 , 478.Xr close 2 , 479.Xr dup 2 , 480.Xr getdtablesize 2 , 481.Xr lseek 2 , 482.Xr read 2 , 483.Xr umask 2 , 484.Xr write 2 485.Sh HISTORY 486An 487.Fn open 488function call appeared in 489.At v6 . 490The 491.Fn openat 492function was introduced in OS X 10.10 493