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