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