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$ 34.\" 35.Dd November 16, 1993 36.Dt OPEN 2 37.Os 38.Sh NAME 39.Nm open 40.Nd open or create a file for reading or writing 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In fcntl.h 45.Ft int 46.Fn open "const char *path" "int flags" "..." 47.Sh DESCRIPTION 48The file name specified by 49.Fa path 50is opened 51for reading and/or writing as specified by the 52argument 53.Fa flags 54and the file descriptor returned to the calling process. 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 63requires a third argument 64.Fa "mode_t mode" , 65and the file is created with mode 66.Fa mode 67as described in 68.Xr chmod 2 69and modified by the process' umask value (see 70.Xr umask 2 ) . 71.Pp 72The flags specified are formed by 73.Em or Ns 'ing 74the following values 75.Pp 76.Bd -literal -offset indent -compact 77O_RDONLY open for reading only 78O_WRONLY open for writing only 79O_RDWR open for reading and writing 80O_NONBLOCK do not block on open 81O_APPEND append on each write 82O_CREAT create file if it does not exist 83O_TRUNC truncate size to 0 84O_EXCL error if create and file exists 85O_SHLOCK atomically obtain a shared lock 86O_EXLOCK atomically obtain an exclusive lock 87O_DIRECT eliminate or reduce cache effects 88O_FSYNC synchronous writes 89O_NOFOLLOW do not follow symlinks 90.Ed 91.Pp 92Opening a file with 93.Dv O_APPEND 94set causes each write on the file 95to be appended to the end. 96If 97.Dv O_TRUNC 98is specified and the 99file exists, the file is truncated to zero length. 100If 101.Dv O_EXCL 102is set with 103.Dv O_CREAT 104and the file already 105exists, 106.Fn open 107returns an error. 108This may be used to 109implement a simple exclusive access locking mechanism. 110If 111.Dv O_EXCL 112is set and the last component of the pathname is 113a symbolic link, 114.Fn open 115will fail even if the symbolic 116link points to a non-existent name. 117If the 118.Dv O_NONBLOCK 119flag is specified and the 120.Fn open 121system call would result 122in the process being blocked for some reason (e.g., waiting for 123carrier on a dialup line), 124.Fn open 125returns immediately. 126The descriptor remains in non-blocking mode for subsequent operations. 127.Pp 128If 129.Dv O_FSYNC 130is used in the mask, all writes will 131immediately be written to disk, 132the kernel will not cache written data 133and all writes on the descriptor will not return until 134the data to be written completes. 135.Pp 136If 137.Dv O_NOFOLLOW 138is used in the mask and the target file passed to 139.Fn open 140is a symbolic link then the 141.Fn open 142will fail. 143.Pp 144When opening a file, a lock with 145.Xr flock 2 146semantics can be obtained by setting 147.Dv O_SHLOCK 148for a shared lock, or 149.Dv O_EXLOCK 150for an exclusive lock. 151If creating a file with 152.Dv O_CREAT , 153the request for the lock will never fail 154(provided that the underlying file system supports locking). 155.Pp 156.Dv O_DIRECT 157may be used to minimize or eliminate the cache effects of reading and writing. 158The system will attempt to avoid caching the data you read or write. 159If it cannot avoid caching the data, 160it will minimize the impact the data has on the cache. 161Use of this flag can drastically reduce performance if not used with care. 162.Pp 163If successful, 164.Fn open 165returns a non-negative integer, termed a file descriptor. 166It returns -1 on failure. 167The file pointer used to mark the current position within the 168file is set to the beginning of the file. 169.Pp 170When a new file is created it is given the group of the directory 171which contains it. 172.Pp 173The new descriptor is set to remain open across 174.Xr execve 2 175system calls; see 176.Xr close 2 177and 178.Xr fcntl 2 . 179.Pp 180The system imposes a limit on the number of file descriptors 181open simultaneously by one process. 182The 183.Xr getdtablesize 2 184system call returns the current system limit. 185.Sh RETURN VALUES 186If successful, 187.Fn open 188returns a non-negative integer, termed a file descriptor. 189It returns -1 on failure, and sets 190.Va errno 191to indicate the error. 192.Sh ERRORS 193The named file is opened unless: 194.Bl -tag -width Er 195.It Bq Er ENOTDIR 196A component of the path prefix is not a directory. 197.It Bq Er ENAMETOOLONG 198A component of a pathname exceeded 255 characters, 199or an entire path name exceeded 1023 characters. 200.It Bq Er ENOENT 201.Dv O_CREAT 202is not set and the named file does not exist. 203.It Bq Er ENOENT 204A component of the path name that must exist does not exist. 205.It Bq Er EACCES 206Search permission is denied for a component of the path prefix. 207.It Bq Er EACCES 208The required permissions (for reading and/or writing) 209are denied for the given flags. 210.It Bq Er EACCES 211.Dv O_CREAT 212is specified, 213the file does not exist, 214and the directory in which it is to be created 215does not permit writing. 216.It Bq Er ELOOP 217Too many symbolic links were encountered in translating the pathname. 218.It Bq Er EISDIR 219The named file is a directory, and the arguments specify 220it is to be opened for writing. 221.It Bq Er EROFS 222The named file resides on a read-only file system, 223and the file is to be modified. 224.It Bq Er EMFILE 225The process has already reached its limit for open file descriptors. 226.It Bq Er ENFILE 227The system file table is full. 228.It Bq Er EMLINK 229.Dv O_NOFOLLOW 230was specified and the target is a symbolic link. 231.It Bq Er ENXIO 232The named file is a character special or block 233special file, and the device associated with this special file 234does not exist. 235.It Bq Er ENXIO 236The named file is a fifo, no process has 237it open for reading, and the arguments specify it is 238to be opened for writing. 239.It Bq Er EINTR 240The 241.Fn open 242operation was interrupted by a signal. 243.It Bq Er EOPNOTSUPP 244.Dv O_SHLOCK 245or 246.Dv O_EXLOCK 247is specified but the underlying file system does not support locking. 248.It Bq Er EOPNOTSUPP 249The named file is a special file mounted through a file system that 250does not support access to it (e.g.\& NFS). 251.It Bq Er EWOULDBLOCK 252.Dv O_NONBLOCK 253and one of 254.Dv O_SHLOCK 255or 256.Dv O_EXLOCK 257is specified and the file is locked. 258.It Bq Er ENOSPC 259.Dv O_CREAT 260is specified, 261the file does not exist, 262and the directory in which the entry for the new file is being placed 263cannot be extended because there is no space left on the file 264system containing the directory. 265.It Bq Er ENOSPC 266.Dv O_CREAT 267is specified, 268the file does not exist, 269and there are no free inodes on the file system on which the 270file is being created. 271.It Bq Er EDQUOT 272.Dv O_CREAT 273is specified, 274the file does not exist, 275and the directory in which the entry for the new file 276is being placed cannot be extended because the 277user's quota of disk blocks on the file system 278containing the directory has been exhausted. 279.It Bq Er EDQUOT 280.Dv O_CREAT 281is specified, 282the file does not exist, 283and the user's quota of inodes on the file system on 284which the file is being created has been exhausted. 285.It Bq Er EIO 286An I/O error occurred while making the directory entry or 287allocating the inode for 288.Dv O_CREAT . 289.It Bq Er ETXTBSY 290The file is a pure procedure (shared text) file that is being 291executed and the 292.Fn open 293system call requests write access. 294.It Bq Er EFAULT 295The 296.Fa path 297argument 298points outside the process's allocated address space. 299.It Bq Er EEXIST 300.Dv O_CREAT 301and 302.Dv O_EXCL 303were specified and the file exists. 304.It Bq Er EOPNOTSUPP 305An attempt was made to open a socket (not currently implemented). 306.It Bq Er EINVAL 307An attempt was made to open a descriptor with an illegal combination 308of 309.Dv O_RDONLY , 310.Dv O_WRONLY , 311and 312.Dv O_RDWR . 313.El 314.Sh SEE ALSO 315.Xr chmod 2 , 316.Xr close 2 , 317.Xr dup 2 , 318.Xr getdtablesize 2 , 319.Xr lseek 2 , 320.Xr read 2 , 321.Xr umask 2 , 322.Xr write 2 , 323.Xr fopen 3 324.Sh HISTORY 325The 326.Fn open 327function appeared in 328.At v6 . 329