bsd/man/man2/open.2

   1 .\"
   2 .\" Copyright (c) 2008 Apple Inc.  All rights reserved.
   3 .\"
   4 .\" @APPLE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. Please obtain a copy of the License at
  10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  11 .\" file.
  12 .\"
  13 .\" The Original Code and all software distributed under the License are
  14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18 .\" Please see the License for the specific language governing rights and
  19 .\" limitations under the License.
  20 .\"
  21 .\" @APPLE_LICENSE_HEADER_END@
  22 .\"
  23 .\"
  24 .\"     $NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd Exp $
  25 .\"
  26 .\" Copyright (c) 1980, 1991, 1993
  27 .\"     The Regents of the University of California.  All rights reserved.
  28 .\"
  29 .\" Redistribution and use in source and binary forms, with or without
  30 .\" modification, are permitted provided that the following conditions
  31 .\" are met:
  32 .\" 1. Redistributions of source code must retain the above copyright
  33 .\"    notice, this list of conditions and the following disclaimer.
  34 .\" 2. Redistributions in binary form must reproduce the above copyright
  35 .\"    notice, this list of conditions and the following disclaimer in the
  36 .\"    documentation and/or other materials provided with the distribution.
  37 .\" 3. All advertising materials mentioning features or use of this software
  38 .\"    must display the following acknowledgement:
  39 .\"     This product includes software developed by the University of
  40 .\"     California, Berkeley and its contributors.
  41 .\" 4. Neither the name of the University nor the names of its contributors
  42 .\"    may be used to endorse or promote products derived from this software
  43 .\"    without specific prior written permission.
  44 .\"
  45 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  46 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  47 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  48 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  49 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  50 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  51 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  52 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  53 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  54 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  55 .\" SUCH DAMAGE.
  56 .\"
  57 .\"     @(#)open.2      8.2 (Berkeley) 11/16/93
  58 .\"
  59 .Dd October 7, 2008
  60 .Dt OPEN 2
  61 .Os BSD 4
  62 .Sh NAME
  63 .Nm open
  64 .Nd open or create a file for reading or writing
  65 .Sh SYNOPSIS
  66 .\" OH??? .Fd #include <sys/stat.h>
  67 .Fd #include <fcntl.h>
  68 .Ft int
  69 .Fo open
  70 .Fa "const char *path"
  71 .Fa "int oflag"
  72 .Fa "..."
  73 .Fc
  74 .Sh DESCRIPTION
  75 The file name specified by
  76 .Fa path
  77 is opened
  78 for reading and/or writing,
  79 as specified by the argument
  80 .Fa oflag ;
  81 the file descriptor is returned to the calling process.
  82 .Pp
  83 The
  84 .Fa oflag
  85 argument may indicate that the file is to be
  86 created if it does not exist (by specifying the
  87 .Dv O_CREAT
  88 flag).  In this case,
  89 .Nm
  90 requires a third argument
  91 .Fa "mode_t mode" ;
  92 the file is created with mode
  93 .Fa mode
  94 as described in
  95 .Xr chmod 2
  96 and modified by the process' umask value (see
  97 .Xr umask 2 ) .
  98 .Pp
  99 The flags specified are formed by
 100 .Em or Ns 'ing
 101 the following values:
 102 .Pp
 103 .Bd -literal -offset indent -compact
 104 O_RDONLY        open for reading only
 105 O_WRONLY        open for writing only
 106 O_RDWR          open for reading and writing
 107 O_NONBLOCK      do not block on open or for data to become available
 108 O_APPEND        append on each write
 109 O_CREAT         create file if it does not exist
 110 O_TRUNC         truncate size to 0
 111 O_EXCL          error if O_CREAT and the file exists
 112 O_SHLOCK        atomically obtain a shared lock
 113 O_EXLOCK        atomically obtain an exclusive lock
 114 O_NOFOLLOW      do not follow symlinks
 115 O_SYMLINK       allow open of symlinks
 116 O_EVTONLY       descriptor requested for event notifications only
 117 .Ed
 118 .Pp
 119 Opening a file with
 120 .Dv O_APPEND
 121 set causes each write on the file to be appended to the end.  If
 122 .Dv O_TRUNC
 123 is specified and the
 124 file exists, the file is truncated to zero length.
 125 If
 126 .Dv O_EXCL
 127 is set with
 128 .Dv O_CREAT
 129 and the file already
 130 exists,
 131 .Fn open
 132 returns an error.
 133 This may be used to implement a simple exclusive-access locking mechanism.
 134 If
 135 .Dv O_EXCL
 136 is set and the last component of the pathname is a symbolic link,
 137 .Fn open
 138 will fail even if the symbolic link points to a non-existent name.
 139 .Pp
 140 If the
 141 .Dv O_NONBLOCK
 142 flag is specified, do not wait for the device or file
 143 to be ready or available.  If the
 144 .Fn open
 145 call would result
 146 in the process being blocked for some reason
 147 (e.g., waiting for carrier on a dialup line),
 148 .Fn open
 149 returns immediately.
 150 This flag also has the effect of making all subsequent I/O
 151 on the open file non-blocking.
 152 .Pp
 153 When opening a file, a lock with
 154 .Xr flock 2
 155 semantics can be obtained by setting
 156 .Dv O_SHLOCK
 157 for a shared lock, or
 158 .Dv O_EXLOCK
 159 for an exclusive lock.
 160 If creating a file with
 161 .Dv O_CREAT ,
 162 the request for the lock will never fail
 163 (provided that the underlying filesystem supports locking).
 164 .Pp
 165 If
 166 .Dv O_NOFOLLOW
 167 is used in the mask and the target file passed to
 168 .Fn open
 169 is a symbolic link then the
 170 .Fn open
 171 will fail.
 172 .Pp
 173 If
 174 .Dv O_SYMLINK
 175 is used in the mask and the target file passed to
 176 .Fn open
 177 is a symbolic link then the
 178 .Fn open
 179 will be for the symbolic link itself, not what it links to.
 180 .Pp
 181 The
 182 .Dv O_EVTONLY
 183 flag is only intended for monitoring a file for changes (e.g. kqueue). Note: when
 184 this flag is used, the opened file will not prevent an unmount
 185 of the volume that contains the file.
 186 .Pp
 187 If successful,
 188 .Fn open
 189 returns a non-negative integer, termed a file descriptor.
 190 It returns -1 on failure.
 191 The file pointer (used to mark the current position within the file)
 192 is set to the beginning of the file.
 193 .Pp
 194 When a new file is created,
 195 it is given the group of the directory which contains it.
 196 .Pp
 197 The new descriptor is set to remain open across
 198 .Xr execve
 199 system calls; see
 200 .Xr close 2
 201 and
 202 .Xr fcntl 2 .
 203 .Pp
 204 The system imposes a limit on the number of file descriptors
 205 that can be held open simultaneously by one process.
 206 .Xr Getdtablesize 2
 207 returns the current system limit.
 208 .Sh RETURN VALUES
 209 If successful,
 210 .Fn open
 211 returns a non-negative integer, termed a file descriptor.
 212 It returns -1 on failure, and sets
 213 .Va errno
 214 to indicate the error.
 215 .Sh ERRORS
 216 The named file is opened unless:
 217 .Bl -tag -width Er
 218 .\" ===========
 219 .It Bq Er EACCES
 220 Search permission is denied for a component of the path prefix.
 221 .\" ===========
 222 .It Bq Er EACCES
 223 The required permissions (for reading and/or writing)
 224 are denied for the given flags.
 225 .\" ===========
 226 .It Bq Er EACCES
 227 .Dv O_CREAT
 228 is specified,
 229 the file does not exist,
 230 and the directory in which it is to be created
 231 does not permit writing.
 232 .\" ===========
 233 .It Bq Er EACCES
 234 .Dv O_TRUNC
 235 is specified and write permission is denied.
 236 .\" ===========
 237 .It Bq Er EAGAIN
 238 .Fa path
 239 specifies the slave side of a locked pseudo-terminal device.
 240 .\" ===========
 241 .It Bq Er EDQUOT
 242 .Dv O_CREAT
 243 is specified,
 244 the file does not exist,
 245 and the directory in which the entry for the new file
 246 is being placed cannot be extended because the
 247 user's quota of disk blocks on the file system
 248 containing the directory has been exhausted.
 249 .\" ===========
 250 .It Bq Er EDQUOT
 251 .Dv O_CREAT
 252 is specified,
 253 the file does not exist,
 254 and the user's quota of inodes on the file system
 255 on which the file is being created has been exhausted.
 256 .\" ===========
 257 .It Bq Er EEXIST
 258 .Dv O_CREAT
 259 and
 260 .Dv O_EXCL
 261 are specified and the file exists.
 262 .\" ===========
 263 .It Bq Er EFAULT
 264 .Fa Path
 265 points outside the process's allocated address space.
 266 .\" ===========
 267 .It Bq Er EINTR
 268 The
 269 .Fn open
 270 operation is interrupted by a signal.
 271 .\" ===========
 272 .It Bq Er EINVAL
 273 The value of
 274 .Fa oflag
 275 is not valid.
 276 .\" ===========
 277 .It Bq Er EIO
 278 An I/O error occurs while making the directory entry or
 279 allocating the inode for
 280 .Dv O_CREAT .
 281 .\" ===========
 282 .It Bq Er EISDIR
 283 The named file is a directory, and the arguments specify
 284 that it is to be opened for writing.
 285 .\" ===========
 286 .It Bq Er ELOOP
 287 Too many symbolic links are encountered in translating the pathname.
 288 This is taken to be indicative of a looping symbolic link.
 289 .\" ===========
 290 .It Bq Er EMFILE
 291 The process has already reached its limit for open file descriptors.
 292 .\" ===========
 293 .It Bq Er ENAMETOOLONG
 294 A component of a pathname exceeds
 295 .Dv {NAME_MAX}
 296 characters, or an entire path name exceeded
 297 .Dv {PATH_MAX}
 298 characters.
 299 .\" ===========
 300 .It Bq Er ENFILE
 301 The system file table is full.
 302 .\" ===========
 303 .It Bq Er ELOOP
 304 .Dv O_NOFOLLOW
 305 was specified and the target is a symbolic link.
 306 .\" ===========
 307 .It Bq Er ENOENT
 308 .Dv O_CREAT
 309 is not set and the named file does not exist.
 310 .\" ===========
 311 .It Bq Er ENOENT
 312 A component of the path name that must exist does not exist.
 313 .\" ===========
 314 .It Bq Er ENOSPC
 315 .Dv O_CREAT
 316 is specified,
 317 the file does not exist,
 318 and the directory in which the entry for the new file is being placed
 319 cannot be extended because there is no space left on the file
 320 system containing the directory.
 321 .\" ===========
 322 .It Bq Er ENOSPC
 323 .Dv O_CREAT
 324 is specified,
 325 the file does not exist,
 326 and there are no free inodes on the file system on which the
 327 file is being created.
 328 .\" ===========
 329 .It Bq Er ENOTDIR
 330 A component of the path prefix is not a directory.
 331 .\" ===========
 332 .It Bq Er ENXIO
 333 The named file is a character-special or block-special file
 334 and the device associated with this special file does not exist.
 335 .\" ===========
 336 .It Bq Er ENXIO
 337 O_NONBLOCK and O_WRONLY are set, the file is a FIFO,
 338 and no process has it open for reading.
 339 .\" ===========
 340 .It Bq Er EOPNOTSUPP
 341 .Dv O_SHLOCK
 342 or
 343 .Dv O_EXLOCK
 344 is specified, but the underlying filesystem does not support locking.
 345 .\" ===========
 346 .It Bq Er EOPNOTSUPP
 347 An attempt is made to open a socket (not currently implemented).
 348 .\" ===========
 349 .It Bq Er EOVERFLOW
 350 The named file is a regular file
 351 and its size does not fit in an object of type off_t.
 352 .\" ===========
 353 .It Bq Er EROFS
 354 The named file resides on a read-only file system,
 355 and the file is to be modified.
 356 .\" ===========
 357 .It Bq Er ETXTBSY
 358 The file is a pure procedure (shared text) file that is being
 359 executed and the
 360 .Fn open
 361 call requests write access.
 362 .El
 363 .Sh COMPATIBILITY
 364 .Fn open
 365 on a terminal device (i.e., /dev/console)
 366 will now make that device a controlling terminal for the process.
 367 Use the O_NOCTTY flag to open a terminal device
 368 without changing your controlling terminal.
 369 .Sh SEE ALSO
 370 .Xr chmod 2 ,
 371 .Xr close 2 ,
 372 .Xr dup 2 ,
 373 .Xr getdtablesize 2 ,
 374 .Xr lseek 2 ,
 375 .Xr read 2 ,
 376 .Xr umask 2 ,
 377 .Xr write 2
 378 .Sh HISTORY
 379 An
 380 .Fn open
 381 function call appeared in
 382 .At v6 .