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