bsd/man/man2/open.2

   1 .\"     $NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd 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
  47 The file name specified by
  48 .Fa path
  49 is opened
  50 for reading and/or writing as specified by the
  51 argument
  52 .Fa flags
  53 and the file descriptor returned to the calling process.
  54 The
  55 .Fa flags
  56 argument may indicate the file is to be
  57 created if it does not exist (by specifying the
  58 .Dv O_CREAT
  59 flag), in which case the file is created with mode
  60 .Fa mode
  61 as described in
  62 .Xr chmod 2
  63 and modified by the process' umask value (see
  64 .Xr umask 2 ) .
  65 .Pp
  66 The flags specified are formed by
  67 .Em or Ns 'ing
  68 the following values
  69 .Pp
  70 .Bd -literal -offset indent -compact
  71 O_RDONLY        open for reading only
  72 O_WRONLY        open for writing only
  73 O_RDWR          open for reading and writing
  74 O_NONBLOCK      do not block on open or for data to become available
  75 O_APPEND        append on each write
  76 O_CREAT         create file if it does not exist
  77 O_TRUNC         truncate size to 0
  78 O_EXCL          error if create and file exists
  79 O_SHLOCK        atomically obtain a shared lock
  80 O_EXLOCK        atomically obtain an exclusive lock
  81 .Ed
  82 .Pp
  83 Opening a file with
  84 .Dv O_APPEND
  85 set causes each write on the file
  86 to be appended to the end.  If
  87 .Dv O_TRUNC
  88 is specified and the
  89 file exists, the file is truncated to zero length.
  90 If
  91 .Dv O_EXCL
  92 is set with
  93 .Dv O_CREAT
  94 and the file already
  95 exists,
  96 .Fn open
  97 returns an error.  This may be used to
  98 implement a simple exclusive access locking mechanism.
  99 If
 100 .Dv O_EXCL
 101 is set and the last component of the pathname is
 102 a symbolic link,
 103 .Fn open
 104 will fail even if the symbolic
 105 link points to a non-existent name.
 106 If the
 107 .Dv O_NONBLOCK
 108 flag is specified, do not wait for the device or file to be ready or
 109 available.  If the
 110 .Fn open
 111 call would result
 112 in the process being blocked for some reason (e.g., waiting for
 113 carrier on a dialup line),
 114 .Fn open
 115 returns immediately.
 116 This flag also has the effect of making all subsequent I/O on the open file non-blocking.
 117 .Pp
 118 When opening a file, a lock with
 119 .Xr flock 2
 120 semantics can be obtained by setting
 121 .Dv O_SHLOCK
 122 for a shared lock, or
 123 .Dv O_EXLOCK
 124 for an exclusive lock.
 125 If creating a file with
 126 .Dv O_CREAT ,
 127 the request for the lock will never fail
 128 (provided that the underlying filesystem supports locking).
 129 .Pp
 130 If successful,
 131 .Fn open
 132 returns a non-negative integer, termed a file descriptor.
 133 It returns -1 on failure.
 134 The file pointer used to mark the current position within the
 135 file is set to the beginning of the file.
 136 .Pp
 137 When a new file is created it is given the group of the directory
 138 which contains it.
 139 .Pp
 140 The new descriptor is set to remain open across
 141 .Xr execve
 142 system calls; see
 143 .Xr close 2
 144 and
 145 .Xr fcntl 2 .
 146 .Pp
 147 The system imposes a limit on the number of file descriptors
 148 open simultaneously by one process.
 149 .Xr Getdtablesize 2
 150 returns the current system limit.
 151 .Sh ERRORS
 152 The named file is opened unless:
 153 .Bl -tag -width Er
 154 .It Bq Er ENOTDIR
 155 A component of the path prefix is not a directory.
 156 .It Bq Er ENAMETOOLONG
 157 A component of a pathname exceeded
 158 .Dv {NAME_MAX}
 159 characters, or an entire path name exceeded
 160 .Dv {PATH_MAX}
 161 characters.
 162 .It Bq Er ENOENT
 163 .Dv O_CREAT
 164 is not set and the named file does not exist.
 165 .It Bq Er ENOENT
 166 A component of the path name that must exist does not exist.
 167 .It Bq Er EACCES
 168 Search permission is denied for a component of the path prefix.
 169 .It Bq Er EACCES
 170 The required permissions (for reading and/or writing)
 171 are denied for the given flags.
 172 .It Bq Er EACCES
 173 .Dv O_CREAT
 174 is specified,
 175 the file does not exist,
 176 and the directory in which it is to be created
 177 does not permit writing.
 178 .It Bq Er ELOOP
 179 Too many symbolic links were encountered in translating the pathname.
 180 .It Bq Er EISDIR
 181 The named file is a directory, and the arguments specify
 182 it is to be opened for writing.
 183 .It Bq Er EROFS
 184 The named file resides on a read-only file system,
 185 and the file is to be modified.
 186 .It Bq Er EMFILE
 187 The process has already reached its limit for open file descriptors.
 188 .It Bq Er ENFILE
 189 The system file table is full.
 190 .It Bq Er ENXIO
 191 The named file is a character special or block
 192 special file, and the device associated with this special file
 193 does not exist.
 194 .It Bq Er EINTR
 195 The
 196 .Fn open
 197 operation was interrupted by a signal.
 198 .It Bq Er EOPNOTSUPP
 199 .Dv O_SHLOCK
 200 or
 201 .Dv O_EXLOCK
 202 is specified but the underlying filesystem does not support locking.
 203 .It Bq Er ENOSPC
 204 .Dv O_CREAT
 205 is specified,
 206 the file does not exist,
 207 and the directory in which the entry for the new file is being placed
 208 cannot be extended because there is no space left on the file
 209 system containing the directory.
 210 .It Bq Er ENOSPC
 211 .Dv O_CREAT
 212 is specified,
 213 the file does not exist,
 214 and there are no free inodes on the file system on which the
 215 file is being created.
 216 .It Bq Er EDQUOT
 217 .Dv O_CREAT
 218 is specified,
 219 the file does not exist,
 220 and the directory in which the entry for the new file
 221 is being placed cannot be extended because the
 222 user's quota of disk blocks on the file system
 223 containing the directory has been exhausted.
 224 .It Bq Er EDQUOT
 225 .Dv O_CREAT
 226 is specified,
 227 the file does not exist,
 228 and the user's quota of inodes on the file system on
 229 which the file is being created has been exhausted.
 230 .It Bq Er EIO
 231 An I/O error occurred while making the directory entry or
 232 allocating the inode for
 233 .Dv O_CREAT .
 234 .It Bq Er ETXTBSY
 235 The file is a pure procedure (shared text) file that is being
 236 executed and the
 237 .Fn open
 238 call requests write access.
 239 .It Bq Er EFAULT
 240 .Fa Path
 241 points outside the process's allocated address space.
 242 .It Bq Er EEXIST
 243 .Dv O_CREAT
 244 and
 245 .Dv O_EXCL
 246 were specified and the file exists.
 247 .It Bq Er EOPNOTSUPP
 248 An attempt was made to open a socket (not currently implemented).
 249 .El
 250 .Sh SEE ALSO
 251 .Xr chmod 2 ,
 252 .Xr close 2 ,
 253 .Xr dup 2 ,
 254 .Xr getdtablesize 2 ,
 255 .Xr lseek 2 ,
 256 .Xr read 2 ,
 257 .Xr write 2 ,
 258 .Xr umask 2
 259 .Sh HISTORY
 260 An
 261 .Fn open
 262 function call appeared in
 263 .At v6 .