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