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