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