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