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