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