bsd/man/man2/open.2

   1 .\"
   2 .\" Copyright (c) 2010 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 November 10, 2010
  60 .Dt OPEN 2
  61 .Os BSD 4
  62 .Sh NAME
  63 .Nm open , openat
  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 .Ft int
  75 .Fn openat "int fd" "const char *path" "int oflag" "..."
  76 .Sh DESCRIPTION
  77 The file name specified by
  78 .Fa path
  79 is opened
  80 for reading and/or writing,
  81 as specified by the argument
  82 .Fa oflag ;
  83 the file descriptor is returned to the calling process.
  84 .Pp
  85 The
  86 .Fa oflag
  87 argument may indicate that the file is to be
  88 created if it does not exist (by specifying the
  89 .Dv O_CREAT
  90 flag).  In this case,
  91 .Fn open
  92 and
  93 .Fn openat
  94 require an additional argument
  95 .Fa "mode_t mode" ;
  96 the file is created with mode
  97 .Fa mode
  98 as described in
  99 .Xr chmod 2
 100 and modified by the process' umask value (see
 101 .Xr umask 2 ) .
 102 .Pp
 103 The
 104 .Fn openat
 105 function is equivalent to the
 106 .Fn open
 107 function except in the case where the
 108 .Fa path
 109 specifies a relative path.
 110 In this case the file to be opened is determined relative to the directory
 111 associated with the file descriptor
 112 .Fa fd
 113 instead of the current working directory.
 114 The
 115 .Fa oflag
 116 argument and the optional fourth argument correspond exactly to
 117 the arguments for
 118 .Fn open .
 119 If
 120 .Fn openat
 121 is passed the special value
 122 .Dv AT_FDCWD
 123 in the
 124 .Fa fd
 125 argument, the current working directory is used
 126 and the behavior is identical to a call to
 127 .Fn open .
 128 .Pp
 129 The flags specified
 130 for the
 131 .Fa oflag
 132 argument must include exactly one of the following file access modes:
 133 .Pp
 134 .Bd -literal -offset indent -compact
 135 O_RDONLY        open for reading only
 136 O_WRONLY        open for writing only
 137 O_RDWR          open for reading and writing
 138 .Ed
 139 .Pp
 140 In addition any combination of the following values can be
 141 .Em or Ns 'ed in
 142 .Fa oflag:
 143 .Pp
 144 .Bd -literal -offset indent -compact
 145 O_NONBLOCK      do not block on open or for data to become available
 146 O_APPEND        append on each write
 147 O_CREAT         create file if it does not exist
 148 O_TRUNC         truncate size to 0
 149 O_EXCL          error if O_CREAT and the file exists
 150 O_SHLOCK        atomically obtain a shared lock
 151 O_EXLOCK        atomically obtain an exclusive lock
 152 O_NOFOLLOW      do not follow symlinks
 153 O_SYMLINK       allow open of symlinks
 154 O_EVTONLY       descriptor requested for event notifications only
 155 O_CLOEXEC       mark as close-on-exec
 156 O_NOFOLLOW_ANY  do not follow symlinks in the entire path.
 157 .Ed
 158 .Pp
 159 Opening a file with
 160 .Dv O_APPEND
 161 set causes each write on the file to be appended to the end.  If
 162 .Dv O_TRUNC
 163 is specified and the
 164 file exists, the file is truncated to zero length.
 165 If
 166 .Dv O_EXCL
 167 is set with
 168 .Dv O_CREAT
 169 and the file already
 170 exists,
 171 .Fn open
 172 returns an error.
 173 This may be used to implement a simple exclusive-access locking mechanism.
 174 If
 175 .Dv O_EXCL
 176 is set with
 177 .Dv O_CREAT
 178 and the last component of the pathname is a symbolic link,
 179 .Fn open
 180 will fail even if the symbolic link points to a non-existent name.
 181 .Pp
 182 If the
 183 .Dv O_NONBLOCK
 184 flag is specified, do not wait for the device or file
 185 to be ready or available.  If the
 186 .Fn open
 187 call would result
 188 in the process being blocked for some reason
 189 (e.g., waiting for carrier on a dialup line),
 190 .Fn open
 191 returns immediately.
 192 This flag also has the effect of making all subsequent I/O
 193 on the open file non-blocking.
 194 .Pp
 195 When opening a file, a lock with
 196 .Xr flock 2
 197 semantics can be obtained by setting
 198 .Dv O_SHLOCK
 199 for a shared lock, or
 200 .Dv O_EXLOCK
 201 for an exclusive lock.
 202 If creating a file with
 203 .Dv O_CREAT ,
 204 the request for the lock will never fail
 205 (provided that the underlying filesystem supports locking).
 206 .Pp
 207 If
 208 .Dv O_NOFOLLOW
 209 is used in the mask and the target file passed to
 210 .Fn open
 211 is a symbolic link then the
 212 .Fn open
 213 will fail.
 214 .Pp
 215 If
 216 .Dv O_SYMLINK
 217 is used in the mask and the target file passed to
 218 .Fn open
 219 is a symbolic link then the
 220 .Fn open
 221 will be for the symbolic link itself, not what it links to.
 222 .Pp
 223 The
 224 .Dv O_EVTONLY
 225 flag is only intended for monitoring a file for changes (e.g. kqueue). Note: when
 226 this flag is used, the opened file will not prevent an unmount
 227 of the volume that contains the file.
 228 .Pp
 229 The
 230 .Dv O_CLOEXEC
 231 flag causes the file descriptor to be marked as close-on-exec,
 232 setting the
 233 .Dv FD_CLOEXEC
 234 flag.  The state of the file descriptor flags can be inspected
 235 using the F_GETFD fcntl.  See
 236 .Xr fcntl 2 .
 237 .Pp
 238 If
 239 .Dv O_NOFOLLOW_ANY
 240 is used in the mask and any component of the path passed to
 241 .Fn open
 242 is a symbolic link then the
 243 .Fn open
 244 will fail.
 245 .Pp
 246 If successful,
 247 .Fn open
 248 returns a non-negative integer, termed a file descriptor.
 249 It returns -1 on failure.
 250 The file pointer (used to mark the current position within the file)
 251 is set to the beginning of the file.
 252 .Pp
 253 When a new file is created,
 254 it is given the group of the directory which contains it.
 255 .Pp
 256 The new descriptor is set to remain open across
 257 .Xr execve
 258 system calls; see
 259 .Xr close 2
 260 and
 261 .Xr fcntl 2 .
 262 .Pp
 263 The system imposes a limit on the number of file descriptors
 264 that can be held open simultaneously by one process.
 265 .Pp
 266 A file's metadata can be updated even if the file was opened in read-only mode.
 267 .Xr Getdtablesize 2
 268 returns the current system limit.
 269 .Sh RETURN VALUES
 270 If successful,
 271 .Fn open
 272 returns a non-negative integer, termed a file descriptor.
 273 It returns -1 on failure, and sets
 274 .Va errno
 275 to indicate the error.
 276 .Sh ERRORS
 277 The named file is opened unless:
 278 .Bl -tag -width Er
 279 .\" ===========
 280 .It Bq Er EACCES
 281 Search permission is denied for a component of the path prefix.
 282 .\" ===========
 283 .It Bq Er EACCES
 284 The required permissions (for reading and/or writing)
 285 are denied for the given flags.
 286 .\" ===========
 287 .It Bq Er EACCES
 288 .Dv O_CREAT
 289 is specified,
 290 the file does not exist,
 291 and the directory in which it is to be created
 292 does not permit writing.
 293 .\" ===========
 294 .It Bq Er EACCES
 295 .Dv O_TRUNC
 296 is specified and write permission is denied.
 297 .\" ===========
 298 .It Bq Er EAGAIN
 299 .Fa path
 300 specifies the slave side of a locked pseudo-terminal device.
 301 .\" ===========
 302 .It Bq Er EDQUOT
 303 .Dv O_CREAT
 304 is specified,
 305 the file does not exist,
 306 and the directory in which the entry for the new file
 307 is being placed cannot be extended because the
 308 user's quota of disk blocks on the file system
 309 containing the directory has been exhausted.
 310 .\" ===========
 311 .It Bq Er EDQUOT
 312 .Dv O_CREAT
 313 is specified,
 314 the file does not exist,
 315 and the user's quota of inodes on the file system
 316 on which the file is being created has been exhausted.
 317 .\" ===========
 318 .It Bq Er EEXIST
 319 .Dv O_CREAT
 320 and
 321 .Dv O_EXCL
 322 are specified and the file exists.
 323 .\" ===========
 324 .It Bq Er EFAULT
 325 .Fa Path
 326 points outside the process's allocated address space.
 327 .\" ===========
 328 .It Bq Er EINTR
 329 The
 330 .Fn open
 331 operation is interrupted by a signal.
 332 .\" ===========
 333 .It Bq Er EINVAL
 334 The value of
 335 .Fa oflag
 336 is not valid.
 337 .\" ===========
 338 .It Bq Er EIO
 339 An I/O error occurs while making the directory entry or
 340 allocating the inode for
 341 .Dv O_CREAT .
 342 .\" ===========
 343 .It Bq Er EISDIR
 344 The named file is a directory, and the arguments specify
 345 that it is to be opened for writing.
 346 .\" ===========
 347 .It Bq Er ELOOP
 348 Too many symbolic links are encountered in translating the pathname.
 349 This is taken to be indicative of a looping symbolic link.
 350 .\" ===========
 351 .It Bq Er EMFILE
 352 The process has already reached its limit for open file descriptors.
 353 .\" ===========
 354 .It Bq Er ENAMETOOLONG
 355 A component of a pathname exceeds
 356 .Dv {NAME_MAX}
 357 characters, or an entire path name exceeded
 358 .Dv {PATH_MAX}
 359 characters.
 360 .\" ===========
 361 .It Bq Er ENFILE
 362 The system file table is full.
 363 .\" ===========
 364 .It Bq Er ELOOP
 365 .Dv O_NOFOLLOW
 366 was specified and the target is a symbolic link.
 367 .\" ===========
 368 .\" ===========
 369 .It Bq Er ELOOP
 370 .Dv O_NOFOLLOW_ANY
 371 was specified and and a component of the path is a symbolic link.
 372 .\" ===========
 373 .It Bq Er ENOENT
 374 .Dv O_CREAT
 375 is not set and the named file does not exist.
 376 .\" ===========
 377 .It Bq Er ENOENT
 378 A component of the path name that must exist does not exist.
 379 .\" ===========
 380 .It Bq Er ENOSPC
 381 .Dv O_CREAT
 382 is specified,
 383 the file does not exist,
 384 and the directory in which the entry for the new file is being placed
 385 cannot be extended because there is no space left on the file
 386 system containing the directory.
 387 .\" ===========
 388 .It Bq Er ENOSPC
 389 .Dv O_CREAT
 390 is specified,
 391 the file does not exist,
 392 and there are no free inodes on the file system on which the
 393 file is being created.
 394 .\" ===========
 395 .It Bq Er ENOTDIR
 396 A component of the path prefix is not a directory.
 397 .\" ===========
 398 .It Bq Er ENXIO
 399 The named file is a character-special or block-special file
 400 and the device associated with this special file does not exist.
 401 .\" ===========
 402 .It Bq Er ENXIO
 403 O_NONBLOCK and O_WRONLY are set, the file is a FIFO,
 404 and no process has it open for reading.
 405 .\" ===========
 406 .It Bq Er EOPNOTSUPP
 407 .Dv O_SHLOCK
 408 or
 409 .Dv O_EXLOCK
 410 is specified, but the underlying filesystem does not support locking.
 411 .\" ===========
 412 .It Bq Er EOPNOTSUPP
 413 An attempt is made to open a socket (not currently implemented).
 414 .\" ===========
 415 .It Bq Er EOVERFLOW
 416 The named file is a regular file
 417 and its size does not fit in an object of type off_t.
 418 .\" ===========
 419 .It Bq Er EROFS
 420 The named file resides on a read-only file system,
 421 and the file is to be modified.
 422 .\" ===========
 423 .It Bq Er ETXTBSY
 424 The file is a pure procedure (shared text) file that is being
 425 executed and the
 426 .Fn open
 427 call requests write access.
 428 .It Bq Eq EBADF
 429 The
 430 .Fa path
 431 argument does not specify an absolute path and the
 432 .Fa fd
 433 argument is
 434 neither
 435 .Dv AT_FDCWD
 436 nor a valid file descriptor open for searching.
 437 .It Bq Eq ENOTDIR
 438 The
 439 .Fa path
 440 argument is not an absolute path and
 441 .Fa fd
 442 is neither
 443 .Dv AT_FDCWD
 444 nor a file descriptor associated with a directory.
 445 .It Bq Eq EILSEQ
 446 The filename does not match the encoding rules.
 447 .El
 448 .Sh COMPATIBILITY
 449 .Fn open
 450 on a terminal device (i.e., /dev/console)
 451 will now make that device a controlling terminal for the process.
 452 Use the O_NOCTTY flag to open a terminal device
 453 without changing your controlling terminal.
 454 .Sh SEE ALSO
 455 .Xr chmod 2 ,
 456 .Xr close 2 ,
 457 .Xr dup 2 ,
 458 .Xr getdtablesize 2 ,
 459 .Xr lseek 2 ,
 460 .Xr read 2 ,
 461 .Xr umask 2 ,
 462 .Xr write 2
 463 .Sh HISTORY
 464 An
 465 .Fn open
 466 function call appeared in
 467 .At v6 .
 468 The
 469 .Fn openat
 470 function was introduced in OS X 10.10