lib/libc/sys/open.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)open.2      8.2 (Berkeley) 11/16/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd February 28, 2009
  32 .Dt OPEN 2
  33 .Os
  34 .Sh NAME
  35 .Nm open , openat
  36 .Nd open or create a file for reading, writing or executing
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In fcntl.h
  41 .Ft int
  42 .Fn open "const char *path" "int flags" "..."
  43 .Ft int
  44 .Fn openat "int fd" "const char *path" "int flags" "..."
  45 .Sh DESCRIPTION
  46 The file name specified by
  47 .Fa path
  48 is opened
  49 for either execution or reading and/or writing as specified by the
  50 argument
  51 .Fa flags
  52 and the file descriptor returned to the calling process.
  53 The
  54 .Fa flags
  55 argument may indicate the file is to be
  56 created if it does not exist (by specifying the
  57 .Dv O_CREAT
  58 flag).
  59 In this case
  60 .Fn open
  61 and
  62 .Fn openat
  63 require an additional argument
  64 .Fa "mode_t mode" ,
  65 and the file is created with mode
  66 .Fa mode
  67 as described in
  68 .Xr chmod 2
  69 and modified by the process' umask value (see
  70 .Xr umask 2 ) .
  71 .Pp
  72 The
  73 .Fn openat
  74 function is equivalent to the
  75 .Fn open
  76 function except in the case where the
  77 .Fa path
  78 specifies a relative path.
  79 In this case the file to be opened is determined relative to the directory
  80 associated with the file descriptor
  81 .Fa fd
  82 instead of the current working directory.
  83 The
  84 .Fa flag
  85 parameter and the optional fourth parameter correspond exactly to
  86 the parameters of
  87 .Fn open .
  88 If
  89 .Fn openat
  90 is passed the special value
  91 .Dv AT_FDCWD
  92 in the
  93 .Fa fd
  94 parameter, the current working directory is used
  95 and the behavior is identical to a call to
  96 .Fn open .
  97 .Pp
  98 The flags specified are formed by
  99 .Em or Ns 'ing
 100 the following values
 101 .Pp
 102 .Bd -literal -offset indent -compact
 103 O_RDONLY        open for reading only
 104 O_WRONLY        open for writing only
 105 O_RDWR          open for reading and writing
 106 O_EXEC          open for execute only
 107 O_NONBLOCK      do not block on open
 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 create and file exists
 112 O_SHLOCK        atomically obtain a shared lock
 113 O_EXLOCK        atomically obtain an exclusive lock
 114 O_DIRECT        eliminate or reduce cache effects
 115 O_FSYNC         synchronous writes
 116 O_SYNC          synchronous writes
 117 O_NOFOLLOW      do not follow symlinks
 118 O_NOCTTY        don't assign controlling terminal
 119 O_TTY_INIT      restore default terminal attributes
 120 .Ed
 121 .Pp
 122 Opening a file with
 123 .Dv O_APPEND
 124 set causes each write on the file
 125 to be appended to the end.
 126 If
 127 .Dv O_TRUNC
 128 is specified and the
 129 file exists, the file is truncated to zero length.
 130 If
 131 .Dv O_EXCL
 132 is set with
 133 .Dv O_CREAT
 134 and the file already
 135 exists,
 136 .Fn open
 137 returns an error.
 138 This may be used to
 139 implement a simple exclusive access locking mechanism.
 140 If
 141 .Dv O_EXCL
 142 is set and the last component of the pathname is
 143 a symbolic link,
 144 .Fn open
 145 will fail even if the symbolic
 146 link points to a non-existent name.
 147 If the
 148 .Dv O_NONBLOCK
 149 flag is specified and the
 150 .Fn open
 151 system call would result
 152 in the process being blocked for some reason (e.g., waiting for
 153 carrier on a dialup line),
 154 .Fn open
 155 returns immediately.
 156 The descriptor remains in non-blocking mode for subsequent operations.
 157 .Pp
 158 If
 159 .Dv O_FSYNC
 160 is used in the mask, all writes will
 161 immediately be written to disk,
 162 the kernel will not cache written data
 163 and all writes on the descriptor will not return until
 164 the data to be written completes.
 165 .Pp
 166 .Dv O_SYNC
 167 is a synonym for
 168 .Dv O_FSYNC
 169 required by
 170 .Tn POSIX .
 171 .Pp
 172 If
 173 .Dv O_NOFOLLOW
 174 is used in the mask and the target file passed to
 175 .Fn open
 176 is a symbolic link then the
 177 .Fn open
 178 will fail.
 179 .Pp
 180 When opening a file, a lock with
 181 .Xr flock 2
 182 semantics can be obtained by setting
 183 .Dv O_SHLOCK
 184 for a shared lock, or
 185 .Dv O_EXLOCK
 186 for an exclusive lock.
 187 If creating a file with
 188 .Dv O_CREAT ,
 189 the request for the lock will never fail
 190 (provided that the underlying file system supports locking).
 191 .Pp
 192 .Dv O_DIRECT
 193 may be used to minimize or eliminate the cache effects of reading and writing.
 194 The system will attempt to avoid caching the data you read or write.
 195 If it cannot avoid caching the data,
 196 it will minimize the impact the data has on the cache.
 197 Use of this flag can drastically reduce performance if not used with care.
 198 .Pp
 199 .Dv O_NOCTTY
 200 may be used to ensure the OS does not assign this file as the
 201 controlling terminal when it opens a tty device.
 202 This is the default on
 203 .Fx ,
 204 but is present for
 205 .Tn POSIX
 206 compatibility.
 207 The
 208 .Fn open
 209 system call will not assign controlling terminals on
 210 .Fx .
 211 .Pp
 212 .Dv O_TTY_INIT
 213 may be used to ensure the OS restores the terminal attributes when
 214 initially opening a TTY.
 215 This is the default on
 216 .Fx ,
 217 but is present for
 218 .Tn POSIX
 219 compatibility.
 220 The initial call to
 221 .Fn open
 222 on a TTY will always restore default terminal attributes on
 223 .Fx .
 224 .Pp
 225 If successful,
 226 .Fn open
 227 returns a non-negative integer, termed a file descriptor.
 228 It returns \-1 on failure.
 229 The file pointer used to mark the current position within the
 230 file is set to the beginning of the file.
 231 .Pp
 232 When a new file is created it is given the group of the directory
 233 which contains it.
 234 .Pp
 235 The new descriptor is set to remain open across
 236 .Xr execve 2
 237 system calls; see
 238 .Xr close 2
 239 and
 240 .Xr fcntl 2 .
 241 .Pp
 242 The system imposes a limit on the number of file descriptors
 243 open simultaneously by one process.
 244 The
 245 .Xr getdtablesize 2
 246 system call returns the current system limit.
 247 .Sh RETURN VALUES
 248 If successful,
 249 .Fn open
 250 and
 251 .Fn openat
 252 return a non-negative integer, termed a file descriptor.
 253 They return \-1 on failure, and set
 254 .Va errno
 255 to indicate the error.
 256 .Sh ERRORS
 257 The named file is opened unless:
 258 .Bl -tag -width Er
 259 .It Bq Er ENOTDIR
 260 A component of the path prefix is not a directory.
 261 .It Bq Er ENAMETOOLONG
 262 A component of a pathname exceeded 255 characters,
 263 or an entire path name exceeded 1023 characters.
 264 .It Bq Er ENOENT
 265 .Dv O_CREAT
 266 is not set and the named file does not exist.
 267 .It Bq Er ENOENT
 268 A component of the path name that must exist does not exist.
 269 .It Bq Er EACCES
 270 Search permission is denied for a component of the path prefix.
 271 .It Bq Er EACCES
 272 The required permissions (for reading and/or writing)
 273 are denied for the given flags.
 274 .It Bq Er EACCES
 275 .Dv O_TRUNC
 276 is specified and write permission is denied.
 277 .It Bq Er EACCES
 278 .Dv O_CREAT
 279 is specified,
 280 the file does not exist,
 281 and the directory in which it is to be created
 282 does not permit writing.
 283 .It Bq Er EPERM
 284 .Dv O_CREAT
 285 is specified, the file does not exist, and the directory in which it is to be
 286 created has its immutable flag set, see the
 287 .Xr chflags 2
 288 manual page for more information.
 289 .It Bq Er EPERM
 290 .Dv The named file has its immutable flag set and the file is to be modified.
 291 .It Bq Er EPERM
 292 .Dv The named file has its append-only flag set, the file is to be modified, and
 293 .Dv O_TRUNC
 294 is specified or
 295 .Dv O_APPEND
 296 is not specified.
 297 .It Bq Er ELOOP
 298 Too many symbolic links were encountered in translating the pathname.
 299 .It Bq Er EISDIR
 300 The named file is a directory, and the arguments specify
 301 it is to be modified.
 302 .It Bq Er EROFS
 303 The named file resides on a read-only file system,
 304 and the file is to be modified.
 305 .It Bq Er EROFS
 306 .Dv O_CREAT
 307 is specified and the named file would reside on a read-only file system.
 308 .It Bq Er EMFILE
 309 The process has already reached its limit for open file descriptors.
 310 .It Bq Er ENFILE
 311 The system file table is full.
 312 .It Bq Er EMLINK
 313 .Dv O_NOFOLLOW
 314 was specified and the target is a symbolic link.
 315 .It Bq Er ENXIO
 316 The named file is a character special or block
 317 special file, and the device associated with this special file
 318 does not exist.
 319 .It Bq Er ENXIO
 320 .Dv O_NONBLOCK
 321 is set, the named file is a fifo,
 322 .Dv O_WRONLY
 323 is set, and no process has the file open for reading.
 324 .It Bq Er EINTR
 325 The
 326 .Fn open
 327 operation was interrupted by a signal.
 328 .It Bq Er EOPNOTSUPP
 329 .Dv O_SHLOCK
 330 or
 331 .Dv O_EXLOCK
 332 is specified but the underlying file system does not support locking.
 333 .It Bq Er EOPNOTSUPP
 334 The named file is a special file mounted through a file system that
 335 does not support access to it (e.g.\& NFS).
 336 .It Bq Er EWOULDBLOCK
 337 .Dv O_NONBLOCK
 338 and one of
 339 .Dv O_SHLOCK
 340 or
 341 .Dv O_EXLOCK
 342 is specified and the file is locked.
 343 .It Bq Er ENOSPC
 344 .Dv O_CREAT
 345 is specified,
 346 the file does not exist,
 347 and the directory in which the entry for the new file is being placed
 348 cannot be extended because there is no space left on the file
 349 system containing the directory.
 350 .It Bq Er ENOSPC
 351 .Dv O_CREAT
 352 is specified,
 353 the file does not exist,
 354 and there are no free inodes on the file system on which the
 355 file is being created.
 356 .It Bq Er EDQUOT
 357 .Dv O_CREAT
 358 is specified,
 359 the file does not exist,
 360 and the directory in which the entry for the new file
 361 is being placed cannot be extended because the
 362 user's quota of disk blocks on the file system
 363 containing the directory has been exhausted.
 364 .It Bq Er EDQUOT
 365 .Dv O_CREAT
 366 is specified,
 367 the file does not exist,
 368 and the user's quota of inodes on the file system on
 369 which the file is being created has been exhausted.
 370 .It Bq Er EIO
 371 An I/O error occurred while making the directory entry or
 372 allocating the inode for
 373 .Dv O_CREAT .
 374 .It Bq Er ETXTBSY
 375 The file is a pure procedure (shared text) file that is being
 376 executed and the
 377 .Fn open
 378 system call requests write access.
 379 .It Bq Er EFAULT
 380 The
 381 .Fa path
 382 argument
 383 points outside the process's allocated address space.
 384 .It Bq Er EEXIST
 385 .Dv O_CREAT
 386 and
 387 .Dv O_EXCL
 388 were specified and the file exists.
 389 .It Bq Er EOPNOTSUPP
 390 An attempt was made to open a socket (not currently implemented).
 391 .It Bq Er EINVAL
 392 An attempt was made to open a descriptor with an illegal combination
 393 of
 394 .Dv O_RDONLY ,
 395 .Dv O_WRONLY ,
 396 .Dv O_RDWR
 397 and
 398 .Dv O_EXEC.
 399 .It Bq Eq EBADF
 400 The
 401 .Fa path
 402 argument does not specify an absolute path and the
 403 .Fa fd
 404 argument is
 405 neither
 406 .Dv AT_FDCWD
 407 nor a valid file descriptor open for searching.
 408 .It Bq Eq ENOTDIR
 409 The
 410 .Fa path
 411 argument is not an absolute path and
 412 .Fa fd
 413 is neither
 414 .Dv AT_FDCWD
 415 nor a file descriptor associated with a directory.
 416 .El
 417 .Sh SEE ALSO
 418 .Xr chmod 2 ,
 419 .Xr close 2 ,
 420 .Xr dup 2 ,
 421 .Xr fexecve 2 ,
 422 .Xr fhopen 2 ,
 423 .Xr getdtablesize 2 ,
 424 .Xr getfh 2 ,
 425 .Xr lgetfh 2 ,
 426 .Xr lseek 2 ,
 427 .Xr read 2 ,
 428 .Xr umask 2 ,
 429 .Xr write 2 ,
 430 .Xr fopen 3
 431 .Sh HISTORY
 432 The
 433 .Fn open
 434 function appeared in
 435 .At v6 .
 436 The
 437 .Fn openat
 438 function was introduced in
 439 .Fx 8.0 .
 440 .Sh BUGS
 441 The Open Group Extended API Set 2 specification requires that the test
 442 for whether
 443 .Fa fd
 444 is searchable is based on whether
 445 .Fa fd
 446 is open for searching, not whether the underlying directory currently
 447 permits searches.
 448 The present implementation of the
 449 .Fa openat
 450 checks the current permissions of directory instead.