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 24, 2009 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 122.Ed 123.Pp 124Opening a file with 125.Dv O_APPEND 126set causes each write on the file 127to be appended to the end. 128If 129.Dv O_TRUNC 130is specified and the 131file exists, the file is truncated to zero length. 132If 133.Dv O_EXCL 134is set with 135.Dv O_CREAT 136and the file already 137exists, 138.Fn open 139returns an error. 140This may be used to 141implement a simple exclusive access locking mechanism. 142If 143.Dv O_EXCL 144is set and the last component of the pathname is 145a symbolic link, 146.Fn open 147will fail even if the symbolic 148link points to a non-existent name. 149If the 150.Dv O_NONBLOCK 151flag is specified and the 152.Fn open 153call would result 154in the process being blocked for some reason (e.g., waiting for 155carrier on a dialup line), 156.Fn open 157returns immediately. 158The first time the process attempts to perform I/O on the open 159file it will block (not currently implemented). 160.Pp 161If 162.Dv O_FSYNC 163is used in the mask, all writes will 164immediately be written to disk, 165the kernel will not cache written data 166and all writes on the descriptor will not return until 167the data to be written completes. 168.Pp 169If 170.Dv O_NOFOLLOW 171is used in the mask and the target file passed to 172.Fn open 173is a symbolic link then the 174.Fn open 175will fail. 176.Pp 177When opening a file, a lock with 178.Xr flock 2 179semantics can be obtained by setting 180.Dv O_SHLOCK 181for a shared lock, or 182.Dv O_EXLOCK 183for an exclusive lock. 184If creating a file with 185.Dv O_CREAT , 186the request for the lock will never fail 187(provided that the underlying filesystem supports locking). 188.Pp 189.Dv O_DIRECT 190may be used to minimize or eliminate the cache effects of reading and writing. 191The system will attempt to avoid caching the data you read or write. 192If it cannot avoid caching the data, 193it will minimize the impact the data has on the cache. 194Use of this flag can drastically reduce performance if not used with care. 195.Pp 196If successful, 197.Fn open 198and 199.Fn openat 200return a non-negative integer, termed a file descriptor. 201It returns -1 on failure. 202The file pointer used to mark the current position within the 203file is set to the beginning of the file. 204.Pp 205When a new file is created it is given the group of the directory 206which contains it. 207.Pp 208The new descriptor is set to remain open across 209.Xr execve 2 210system calls; see 211.Xr close 2 212and 213.Xr fcntl 2 . 214.Pp 215The system imposes a limit on the number of file descriptors 216open simultaneously by one process. 217.Xr Getdtablesize 2 218returns the current system limit. 219.Sh RETURN VALUES 220If successful, 221.Fn open 222and 223.Fn openat 224return a non-negative integer, termed a file descriptor. 225They return -1 on failure, and set 226.Va errno 227to indicate the error. 228.Sh ERRORS 229The named file is opened unless: 230.Bl -tag -width Er 231.It Bq Er ENOTDIR 232A component of the path prefix is not a directory or the 233.Fa path 234argument is not an absolute path and the 235.Fa fd 236argument is neither 237.Dv AT_FDCWD 238nor a file descriptor associated with a directory. 239.It Bq Er ENAMETOOLONG 240A component of a pathname exceeded 255 characters, 241or an entire path name exceeded 1023 characters. 242.It Bq Er ENOENT 243.Dv O_CREAT 244is not set and the named file does not exist. 245.It Bq Er ENOENT 246A component of the path name that must exist does not exist. 247.It Bq Er EACCES 248Search permission is denied for a component of the path prefix. 249.It Bq Er EACCES 250The required permissions (for reading and/or writing) 251are denied for the given flags. 252.It Bq Er EACCES 253.Dv O_CREAT 254is specified, 255the file does not exist, 256and the directory in which it is to be created 257does not permit writing. 258.It Bq Er ELOOP 259Too many symbolic links were encountered in translating the pathname. 260.It Bq Er EISDIR 261The named file is a directory, and the arguments specify 262it is to be opened for writing. 263.It Bq Er EROFS 264The named file resides on a read-only file system, 265and the file is to be modified. 266.It Bq Er EMFILE 267The process has already reached its limit for open file descriptors. 268.It Bq Er ENFILE 269The system file table is full. 270.It Bq Er EMLINK 271.Dv O_NOFOLLOW 272was specified and the target is a symbolic link. 273.It Bq Er ENXIO 274The named file is a character special or block 275special file, and the device associated with this special file 276does not exist. 277.It Bq Er ENXIO 278The named file is a fifo, no process has 279it open for reading, and the arguments specify it is 280to be opened for writing. 281.It Bq Er EINTR 282The 283.Fn open 284operation was interrupted by a signal. 285.It Bq Er EOPNOTSUPP 286.Dv O_SHLOCK 287or 288.Dv O_EXLOCK 289is specified but the underlying filesystem does not support locking. 290.It Bq Er EWOULDBLOCK 291.Dv O_NONBLOCK 292and one of 293.Dv O_SHLOCK 294or 295.Dv O_EXLOCK 296is specified and the file is locked. 297.It Bq Er ENOSPC 298.Dv O_CREAT 299is specified, 300the file does not exist, 301and the directory in which the entry for the new file is being placed 302cannot be extended because there is no space left on the file 303system containing the directory. 304.It Bq Er ENOSPC 305.Dv O_CREAT 306is specified, 307the file does not exist, 308and there are no free inodes on the file system on which the 309file is being created. 310.It Bq Er EDQUOT 311.Dv O_CREAT 312is specified, 313the file does not exist, 314and the directory in which the entry for the new file 315is being placed cannot be extended because the 316user's quota of disk blocks on the file system 317containing the directory has been exhausted. 318.It Bq Er EDQUOT 319.Dv O_CREAT 320is specified, 321the file does not exist, 322and the user's quota of inodes on the file system on 323which the file is being created has been exhausted. 324.It Bq Er EIO 325An I/O error occurred while making the directory entry or 326allocating the inode for 327.Dv O_CREAT . 328.It Bq Er ETXTBSY 329The file is a pure procedure (shared text) file that is being 330executed and the 331.Fn open 332call requests write access. 333.It Bq Er EFAULT 334.Fa Path 335points outside the process's allocated address space. 336.It Bq Er EEXIST 337.Dv O_CREAT 338and 339.Dv O_EXCL 340were specified and the file exists. 341.It Bq Er EOPNOTSUPP 342An attempt was made to open a socket (not currently implemented). 343.It Bq Er EINVAL 344An attempt was made to open a descriptor with an illegal combination 345of 346.Dv O_RDONLY , 347.Dv O_WRONLY , 348and 349.Dv O_RDWR . 350.El 351.Sh SEE ALSO 352.Xr chmod 2 , 353.Xr close 2 , 354.Xr dup 2 , 355.Xr getdtablesize 2 , 356.Xr lseek 2 , 357.Xr read 2 , 358.Xr umask 2 , 359.Xr write 2 360.Sh HISTORY 361An 362.Fn open 363function call appeared in 364.At v6 . 365An 366.Fn openat 367function call appeared first in Solaris and was ported to 368.Dx 2.3 . 369.Sh BUGS 370The Open Group Extended API Set 2 specification requires that the test 371for 372.Fa fd Ap s 373searchability is based on whether it is open for searching, 374and not whether the underlying directory currently permits searches. 375The present implementation of 376.Fn openat 377checks the current permissions of directory instead. 378