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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)open.2 8.2 (Berkeley) 11/16/93 33.\" $FreeBSD: src/lib/libc/sys/open.2,v 1.11.2.9 2001/12/14 18:34:01 ru Exp $ 34.\" $DragonFly: src/lib/libc/sys/open.2,v 1.3 2005/07/29 23:16:04 hsu Exp $ 35.\" 36.Dd July 31, 2012 37.Dt OPEN 2 38.Os 39.Sh NAME 40.Nm open , openat 41.Nd open or create a file for reading or writing 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In fcntl.h 46.Ft int 47.Fn open "const char *path" "int flags" "..." 48.Ft int 49.Fn openat "int fd" "const char *path" "int flags" "..." 50.Sh DESCRIPTION 51The file name specified by 52.Fa path 53is opened 54for reading and/or writing as specified by the 55argument 56.Fa flags 57and the lowest unused file descriptor in the process' file descriptor table 58is returned. 59The 60.Fa flags 61argument may indicate the file is to be 62created if it does not exist (by specifying the 63.Dv O_CREAT 64flag). 65In this case 66.Fn open 67and 68.Fn openat 69require a third argument 70.Fa "mode_t mode" , 71and the file is created with mode 72.Fa mode 73as described in 74.Xr chmod 2 75and modified by the process' umask value (see 76.Xr umask 2 ) . 77.Pp 78The 79.Fn openat 80function is equivalent to the 81.Fn open 82function except in the case where the 83.Fa path 84specifies a relative path. 85In this case the file to be opened is determined relative to the directory 86associated with the file descriptor 87.Fa fd 88instead of the current working directory. 89The 90.Fa flag 91parameter and the optional fourth parameter correspond exactly to 92the parameters of 93.Fn open . 94If 95.Fn openat 96is passed the special value 97.Dv AT_FDCWD 98in the 99.Fa fd 100parameter, the current working directory is used 101and the behavior is identical to a call to 102.Fn open . 103.Pp 104The flags specified are formed by 105.Em or Ns 'ing 106the following values 107.Pp 108.Bd -literal -offset indent -compact 109O_RDONLY open for reading only 110O_WRONLY open for writing only 111O_RDWR open for reading and writing 112O_NONBLOCK do not block on open 113O_APPEND append on each write 114O_CREAT create file if it does not exist 115O_TRUNC truncate size to 0 116O_EXCL error if create and file exists 117O_SHLOCK atomically obtain a shared lock 118O_EXLOCK atomically obtain an exclusive lock 119O_DIRECT eliminate or reduce cache effects 120O_FSYNC synchronous writes 121O_NOFOLLOW do not follow symlinks 122O_DIRECTORY error if file is not a directory 123O_CLOEXEC set FD_CLOEXEC upon open 124.Ed 125.Pp 126Opening a file with 127.Dv O_APPEND 128set causes each write on the file 129to be appended to the end. 130If 131.Dv O_TRUNC 132is specified and the 133file exists, the file is truncated to zero length. 134If 135.Dv O_EXCL 136is set with 137.Dv O_CREAT 138and the file already 139exists, 140.Fn open 141returns an error. 142This may be used to 143implement a simple exclusive access locking mechanism. 144If 145.Dv O_EXCL 146is set and the last component of the pathname is 147a symbolic link, 148.Fn open 149will fail even if the symbolic 150link points to a non-existent name. 151If the 152.Dv O_NONBLOCK 153flag is specified and the 154.Fn open 155call would result 156in the process being blocked for some reason (e.g., waiting for 157carrier on a dialup line), 158.Fn open 159returns immediately. 160The first time the process attempts to perform I/O on the open 161file it will block (not currently implemented). 162.Pp 163If 164.Dv O_FSYNC 165is used in the mask, all writes will 166immediately be written to disk, 167the kernel will not cache written data 168and all writes on the descriptor will not return until 169the data to be written completes. 170.Pp 171If 172.Dv O_NOFOLLOW 173is used in the mask and the target file passed to 174.Fn open 175is a symbolic link then the 176.Fn open 177will fail. 178.Pp 179When opening a file, a lock with 180.Xr flock 2 181semantics can be obtained by setting 182.Dv O_SHLOCK 183for a shared lock, or 184.Dv O_EXLOCK 185for an exclusive lock. 186If creating a file with 187.Dv O_CREAT , 188the request for the lock will never fail 189(provided that the underlying filesystem supports locking). 190.Pp 191.Dv O_DIRECT 192may be used to minimize or eliminate the cache effects of reading and writing. 193The system will attempt to avoid caching the data you read or write. 194If it cannot avoid caching the data, 195it will minimize the impact the data has on the cache. 196Use of this flag can drastically reduce performance if not used with care. 197.Pp 198.Dv O_DIRECTORY 199may be used to ensure the resulting file descriptor refers to a directory. 200This flag can be used to prevent applications with elevated privileges 201from opening files which are even unsafe to open with 202.Dv O_RDONLY , 203such as device nodes. 204.Pp 205.Dv O_CLOEXEC 206may be used to atomically set the 207.Dv FD_CLOEXEC 208flag for the newly returned file descriptor. 209.Pp 210If successful, 211.Fn open 212and 213.Fn openat 214return a non-negative integer, termed a file descriptor. 215It returns -1 on failure. 216The file pointer used to mark the current position within the 217file is set to the beginning of the file. 218.Pp 219When a new file is created it is given the group of the directory 220which contains it. 221.Pp 222Unless 223.Dv 224O_CLOEXEC 225was specified, 226the new descriptor is set to remain open across 227.Xr execve 2 228system calls; see 229.Xr close 2 , 230.Xr fcntl 2 231and 232.Dv O_CLOEXEC 233description. 234.Pp 235The system imposes a limit on the number of file descriptors 236open simultaneously by one process. 237.Xr Getdtablesize 2 238returns the current system limit. 239.Sh RETURN VALUES 240If successful, 241.Fn open 242and 243.Fn openat 244return a non-negative integer, termed a file descriptor. 245They return -1 on failure, and set 246.Va errno 247to indicate the error. 248.Sh ERRORS 249The named file is opened unless: 250.Bl -tag -width Er 251.It Bq Er ENOTDIR 252A component of the path prefix is not a directory or the 253.Fa path 254argument is not an absolute path and the 255.Fa fd 256argument is neither 257.Dv AT_FDCWD 258nor a file descriptor associated with a directory or 259.Dv O_DIRECTORY 260is specified and the file is not a directory. 261.It Bq Er ENAMETOOLONG 262A component of a pathname exceeded 255 characters, 263or an entire path name exceeded 1023 characters. 264.It Bq Er ENOENT 265.Dv O_CREAT 266is not set and the named file does not exist. 267.It Bq Er ENOENT 268A component of the path name that must exist does not exist. 269.It Bq Er EACCES 270Search permission is denied for a component of the path prefix. 271.It Bq Er EACCES 272The required permissions (for reading and/or writing) 273are denied for the given flags. 274.It Bq Er EACCES 275.Dv O_CREAT 276is specified, 277the file does not exist, 278and the directory in which it is to be created 279does not permit writing. 280.It Bq Er ELOOP 281Too many symbolic links were encountered in translating the pathname. 282.It Bq Er EISDIR 283The named file is a directory, and the arguments specify 284it is to be opened for writing. 285.It Bq Er EROFS 286The named file resides on a read-only file system, 287and the file is to be modified. 288.It Bq Er EMFILE 289The process has already reached its limit for open file descriptors. 290.It Bq Er ENFILE 291The system file table is full. 292.It Bq Er EMLINK 293.Dv O_NOFOLLOW 294was specified and the target is a symbolic link. 295.It Bq Er ENXIO 296The named file is a character special or block 297special file, and the device associated with this special file 298does not exist. 299.It Bq Er ENXIO 300The named file is a fifo, no process has 301it open for reading, and the arguments specify it is 302to be opened for writing. 303.It Bq Er EINTR 304The 305.Fn open 306operation was interrupted by a signal. 307.It Bq Er EOPNOTSUPP 308.Dv O_SHLOCK 309or 310.Dv O_EXLOCK 311is specified but the underlying filesystem does not support locking. 312.It Bq Er EWOULDBLOCK 313.Dv O_NONBLOCK 314and one of 315.Dv O_SHLOCK 316or 317.Dv O_EXLOCK 318is specified and the file is locked. 319.It Bq Er ENOSPC 320.Dv O_CREAT 321is specified, 322the file does not exist, 323and the directory in which the entry for the new file is being placed 324cannot be extended because there is no space left on the file 325system containing the directory. 326.It Bq Er ENOSPC 327.Dv O_CREAT 328is specified, 329the file does not exist, 330and there are no free inodes on the file system on which the 331file is being created. 332.It Bq Er EDQUOT 333.Dv O_CREAT 334is specified, 335the file does not exist, 336and the directory in which the entry for the new file 337is being placed cannot be extended because the 338user's quota of disk blocks on the file system 339containing the directory has been exhausted. 340.It Bq Er EDQUOT 341.Dv O_CREAT 342is specified, 343the file does not exist, 344and the user's quota of inodes on the file system on 345which the file is being created has been exhausted. 346.It Bq Er EIO 347An I/O error occurred while making the directory entry or 348allocating the inode for 349.Dv O_CREAT . 350.It Bq Er ETXTBSY 351The file is a pure procedure (shared text) file that is being 352executed and the 353.Fn open 354call requests write access. 355.It Bq Er EFAULT 356.Fa Path 357points outside the process's allocated address space. 358.It Bq Er EEXIST 359.Dv O_CREAT 360and 361.Dv O_EXCL 362were specified and the file exists. 363.It Bq Er EOPNOTSUPP 364An attempt was made to open a socket (not currently implemented). 365.It Bq Er EINVAL 366An attempt was made to open a descriptor with an illegal combination 367of 368.Dv O_RDONLY , 369.Dv O_WRONLY , 370and 371.Dv O_RDWR . 372.El 373.Sh SEE ALSO 374.Xr chmod 2 , 375.Xr close 2 , 376.Xr dup 2 , 377.Xr getdtablesize 2 , 378.Xr lseek 2 , 379.Xr read 2 , 380.Xr umask 2 , 381.Xr write 2 382.Sh HISTORY 383An 384.Fn open 385function call appeared in 386.At v6 . 387An 388.Fn openat 389function call appeared first in Solaris and was ported to 390.Dx 2.3 . 391.Sh BUGS 392The Open Group Extended API Set 2 specification requires that the test 393for 394.Fa fd Ap s 395searchability is based on whether it is open for searching, 396and not whether the underlying directory currently permits searches. 397The present implementation of 398.Fn openat 399checks the current permissions of directory instead. 400