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