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 O_CLOEXEC 224was specified, the new descriptor is set to remain open across 225.Xr execve 2 226system calls; see 227.Xr close 2 , 228.Xr fcntl 2 229and 230.Dv O_CLOEXEC 231description. 232.Pp 233The system imposes a limit on the number of file descriptors 234open simultaneously by one process. 235.Xr Getdtablesize 2 236returns the current system limit. 237.Sh RETURN VALUES 238If successful, 239.Fn open 240and 241.Fn openat 242return a non-negative integer, termed a file descriptor. 243They return -1 on failure, and set 244.Va errno 245to indicate the error. 246.Sh ERRORS 247The named file is opened unless: 248.Bl -tag -width Er 249.It Bq Er ENOTDIR 250A component of the path prefix is not a directory or the 251.Fa path 252argument is not an absolute path and the 253.Fa fd 254argument is neither 255.Dv AT_FDCWD 256nor a file descriptor associated with a directory or 257.Dv O_DIRECTORY 258is specified and the file is not a directory. 259.It Bq Er ENAMETOOLONG 260A component of a pathname exceeded 255 characters, 261or an entire path name exceeded 1023 characters. 262.It Bq Er ENOENT 263.Dv O_CREAT 264is not set and the named file does not exist. 265.It Bq Er ENOENT 266A component of the path name that must exist does not exist. 267.It Bq Er EACCES 268Search permission is denied for a component of the path prefix. 269.It Bq Er EACCES 270The required permissions (for reading and/or writing) 271are denied for the given flags. 272.It Bq Er EACCES 273.Dv O_CREAT 274is specified, 275the file does not exist, 276and the directory in which it is to be created 277does not permit writing. 278.It Bq Er ELOOP 279Too many symbolic links were encountered in translating the pathname. 280.It Bq Er EISDIR 281The named file is a directory, and the arguments specify 282it is to be opened for writing. 283.It Bq Er EROFS 284The named file resides on a read-only file system, 285and the file is to be modified. 286.It Bq Er EMFILE 287The process has already reached its limit for open file descriptors. 288.It Bq Er ENFILE 289The system file table is full. 290.It Bq Er EMLINK 291.Dv O_NOFOLLOW 292was specified and the target is a symbolic link. 293.It Bq Er ENXIO 294The named file is a character special or block 295special file, and the device associated with this special file 296does not exist. 297.It Bq Er ENXIO 298The named file is a fifo, no process has 299it open for reading, and the arguments specify it is 300to be opened for writing. 301.It Bq Er EINTR 302The 303.Fn open 304operation was interrupted by a signal. 305.It Bq Er EOPNOTSUPP 306.Dv O_SHLOCK 307or 308.Dv O_EXLOCK 309is specified but the underlying filesystem does not support locking. 310.It Bq Er EWOULDBLOCK 311.Dv O_NONBLOCK 312and one of 313.Dv O_SHLOCK 314or 315.Dv O_EXLOCK 316is specified and the file is locked. 317.It Bq Er ENOSPC 318.Dv O_CREAT 319is specified, 320the file does not exist, 321and the directory in which the entry for the new file is being placed 322cannot be extended because there is no space left on the file 323system containing the directory. 324.It Bq Er ENOSPC 325.Dv O_CREAT 326is specified, 327the file does not exist, 328and there are no free inodes on the file system on which the 329file is being created. 330.It Bq Er EDQUOT 331.Dv O_CREAT 332is specified, 333the file does not exist, 334and the directory in which the entry for the new file 335is being placed cannot be extended because the 336user's quota of disk blocks on the file system 337containing the directory has been exhausted. 338.It Bq Er EDQUOT 339.Dv O_CREAT 340is specified, 341the file does not exist, 342and the user's quota of inodes on the file system on 343which the file is being created has been exhausted. 344.It Bq Er EIO 345An I/O error occurred while making the directory entry or 346allocating the inode for 347.Dv O_CREAT . 348.It Bq Er ETXTBSY 349The file is a pure procedure (shared text) file that is being 350executed and the 351.Fn open 352call requests write access. 353.It Bq Er EFAULT 354.Fa Path 355points outside the process's allocated address space. 356.It Bq Er EEXIST 357.Dv O_CREAT 358and 359.Dv O_EXCL 360were specified and the file exists. 361.It Bq Er EOPNOTSUPP 362An attempt was made to open a socket (not currently implemented). 363.It Bq Er EINVAL 364An attempt was made to open a descriptor with an illegal combination 365of 366.Dv O_RDONLY , 367.Dv O_WRONLY , 368and 369.Dv O_RDWR . 370.El 371.Sh SEE ALSO 372.Xr chmod 2 , 373.Xr close 2 , 374.Xr dup 2 , 375.Xr getdtablesize 2 , 376.Xr lseek 2 , 377.Xr read 2 , 378.Xr umask 2 , 379.Xr write 2 380.Sh HISTORY 381An 382.Fn open 383function call appeared in 384.At v6 . 385An 386.Fn openat 387function call appeared first in Solaris and was ported to 388.Dx 2.3 . 389.Sh BUGS 390The Open Group Extended API Set 2 specification requires that the test 391for 392.Fa fd Ap s 393searchability is based on whether it is open for searching, 394and not whether the underlying directory currently permits searches. 395The present implementation of 396.Fn openat 397checks the current permissions of directory instead. 398