1.\" $NetBSD: open.2,v 1.15 1998/08/29 08:32:40 lukem Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)open.2 8.2 (Berkeley) 11/16/93 35.\" 36.Dd November 16, 1993 37.Dt OPEN 2 38.Os BSD 4 39.Sh NAME 40.Nm open 41.Nd open or create a file for reading or writing 42.Sh SYNOPSIS 43.Fd #include <fcntl.h> 44.Ft int 45.Fn open "const char *path" "int flags" "mode_t mode" 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 file descriptor returned to the calling process. 54The 55.Fa flags 56are specified by 57.Em or Ns 'ing 58the following values. 59Applications must specify exactly one of the first three values 60(file access modes): 61.Bl -tag -offset indent -width O_NONBLOCK 62.It Dv O_RDONLY 63Open for reading only. 64.It Dv O_WRONLY 65Open for writing only. 66.It Dv O_RDWR 67Open for reading and writing. 68.El 69.Pp 70Any combination of the following may be used: 71.Bl -tag -offset indent -width O_NONBLOCK 72.It Dv O_NONBLOCK 73Do not block on open or for data to become available. 74.It Dv O_APPEND 75Append to the file on each write. 76.It Dv O_CREAT 77Create the file if it does not exist, in which case the file is 78created with mode 79.Ar mode 80as described in 81.Xr chmod 2 82and modified by the process' umask value (see 83.Xr umask 2 ) . 84.It Dv O_TRUNC 85Truncate size to 0. 86.It Dv O_EXCL 87Error if 88.Dv O_CREAT 89and the file already exists. 90.It Dv O_SHLOCK 91Atomically obtain a shared lock. 92.It Dv O_EXLOCK 93Atomically obtain an exclusive lock. 94.It Dv O_DSYNC 95If set, write operations will be performed according to synchronized 96I/O data integrity completion: 97each write will wait for the file data to be committed to stable 98storage. 99.It Dv O_SYNC 100If set, write operations will be performed according to synchronized 101I/O file integrity completion: 102each write will wait for both the file data and file status to be 103committed to stable storage. 104.It Dv O_RSYNC 105If set, read operations will complete at the same level of 106integrity which is in effect for write operations: 107if specified together with 108.Dv O_SYNC , 109each read will wait for the file status to be committed to stable 110storage. 111.Pp 112Combining 113.Dv O_RSYNC 114with 115.Dv O_DSYNC 116only, or specifying it without any other synchronized I/O integrity 117completion flag set, has no further effect. 118.El 119.Pp 120Opening a file with 121.Dv O_APPEND 122set causes each write on the file 123to be appended to the end. 124If 125.Dv O_TRUNC 126is specified and the 127file exists, the file is truncated to zero length. 128.Pp 129If 130.Dv O_EXCL 131is set with 132.Dv O_CREAT 133and the file already 134exists, 135.Fn open 136returns an error. 137This may be used to implement a simple exclusive access locking mechanism. 138If 139.Dv O_EXCL 140is set and the last component of the pathname is 141a symbolic link, 142.Fn open 143will fail even if the symbolic 144link points to a non-existent name. 145.Pp 146If the 147.Dv O_NONBLOCK 148flag is specified, do not wait for the device or file to be ready or 149available. 150If the 151.Fn open 152call would result 153in the process being blocked for some reason (e.g., waiting for 154carrier on a dialup line), 155.Fn open 156returns immediately. 157This flag also has the effect of making all subsequent I/O on the open file non-blocking. 158.Pp 159When opening a file, a lock with 160.Xr flock 2 161semantics can be obtained by setting 162.Dv O_SHLOCK 163for a shared lock, or 164.Dv O_EXLOCK 165for an exclusive lock. 166If creating a file with 167.Dv O_CREAT , 168the request for the lock will never fail 169(provided that the underlying filesystem supports locking). 170.Pp 171If successful, 172.Fn open 173returns a non-negative integer, termed a file descriptor. 174It returns -1 on failure. 175The file pointer used to mark the current position within the 176file is set to the beginning of the file. 177.Pp 178When a new file is created it is given the group of the directory 179which contains it. 180.Pp 181The new descriptor is set to remain open across 182.Xr execve 2 183system calls; see 184.Xr close 2 185and 186.Xr fcntl 2 . 187.Pp 188The system imposes a limit on the number of file descriptors 189open simultaneously by one process. 190Calling 191.Xr getdtablesize 3 192returns the current system limit. 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 200.Dv {NAME_MAX} 201characters, or an entire path name exceeded 202.Dv {PATH_MAX} 203characters. 204.It Bq Er ENOENT 205.Dv O_CREAT 206is not set and the named file does not exist. 207.It Bq Er ENOENT 208A component of the path name that must exist does not exist. 209.It Bq Er EACCES 210Search permission is denied for a component of the path prefix. 211.It Bq Er EACCES 212The required permissions (for reading and/or writing) 213are denied for the given flags. 214.It Bq Er EACCES 215.Dv O_CREAT 216is specified, 217the file does not exist, 218and the directory in which it is to be created 219does not permit writing. 220.It Bq Er ELOOP 221Too many symbolic links were encountered in translating the pathname. 222.It Bq Er EISDIR 223The named file is a directory, and the arguments specify 224it is to be opened for writing. 225.It Bq Er EROFS 226The named file resides on a read-only file system, 227and the file is to be modified. 228.It Bq Er EMFILE 229The process has already reached its limit for open file descriptors. 230.It Bq Er ENFILE 231The system file table is full. 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 EINTR 237The 238.Fn open 239operation was interrupted by a signal. 240.It Bq Er EOPNOTSUPP 241.Dv O_SHLOCK 242or 243.Dv O_EXLOCK 244is specified but the underlying filesystem does not support locking. 245.It Bq Er ENOSPC 246.Dv O_CREAT 247is specified, 248the file does not exist, 249and the directory in which the entry for the new file is being placed 250cannot be extended because there is no space left on the file 251system containing the directory. 252.It Bq Er ENOSPC 253.Dv O_CREAT 254is specified, 255the file does not exist, 256and there are no free inodes on the file system on which the 257file is being created. 258.It Bq Er EDQUOT 259.Dv O_CREAT 260is specified, 261the file does not exist, 262and the directory in which the entry for the new file 263is being placed cannot be extended because the 264user's quota of disk blocks on the file system 265containing the directory has been exhausted. 266.It Bq Er EDQUOT 267.Dv O_CREAT 268is specified, 269the file does not exist, 270and the user's quota of inodes on the file system on 271which the file is being created has been exhausted. 272.It Bq Er EIO 273An I/O error occurred while making the directory entry or 274allocating the inode for 275.Dv O_CREAT . 276.It Bq Er ETXTBSY 277The file is a pure procedure (shared text) file that is being 278executed and the 279.Fn open 280call requests write access. 281.It Bq Er EFAULT 282.Fa path 283points outside the process's allocated address space. 284.It Bq Er EEXIST 285.Dv O_CREAT 286and 287.Dv O_EXCL 288were specified and the file exists. 289.It Bq Er EOPNOTSUPP 290An attempt was made to open a socket (not currently implemented). 291.El 292.Sh SEE ALSO 293.Xr chmod 2 , 294.Xr close 2 , 295.Xr dup 2 , 296.Xr lseek 2 , 297.Xr read 2 , 298.Xr write 2 , 299.Xr umask 2 , 300.Xr getdtablesize 3 301.Sh STANDARDS 302The 303.Fn open 304function conforms to 305.St -p1003.1-90 . 306The 307.Fa flags 308values 309.Dv O_DSYNC , 310.Dv O_SYNC 311and 312.Dv O_RSYNC 313are extensions defined in 314.St -p1003.1b-93 . 315.Sh HISTORY 316An 317.Fn open 318function call appeared in 319.At v6 . 320