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 November 16, 1993
  37 .Dt OPEN 2
  38 .Os
  39 .Sh NAME
  40 .Nm open
  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 .Sh DESCRIPTION
  49 The file name specified by
  50 .Fa path
  51 is opened
  52 for reading and/or writing as specified by the
  53 argument
  54 .Fa flags
  55 and the lowest unused file descriptor in the process' file descriptor table
  56 is returned.
  57 The
  58 .Fa flags
  59 argument may indicate the file is to be
  60 created if it does not exist (by specifying the
  61 .Dv O_CREAT
  62 flag).
  63 In this case
  64 .Nm
  65 requires 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 flags specified are formed by
  75 .Em or Ns 'ing
  76 the following values
  77 .Pp
  78 .Bd -literal -offset indent -compact
  79 O_RDONLY        open for reading only
  80 O_WRONLY        open for writing only
  81 O_RDWR          open for reading and writing
  82 O_NONBLOCK      do not block on open
  83 O_APPEND        append on each write
  84 O_CREAT         create file if it does not exist
  85 O_TRUNC         truncate size to 0
  86 O_EXCL          error if create and file exists
  87 O_SHLOCK        atomically obtain a shared lock
  88 O_EXLOCK        atomically obtain an exclusive lock
  89 O_DIRECT        eliminate or reduce cache effects
  90 O_FSYNC         synchronous writes
  91 O_NOFOLLOW      do not follow symlinks
  92 .Ed
  93 .Pp
  94 Opening a file with
  95 .Dv O_APPEND
  96 set causes each write on the file
  97 to be appended to the end.
  98 If
  99 .Dv O_TRUNC
 100 is specified and the
 101 file exists, the file is truncated to zero length.
 102 If
 103 .Dv O_EXCL
 104 is set with
 105 .Dv O_CREAT
 106 and the file already
 107 exists,
 108 .Fn open
 109 returns an error.
 110 This may be used to
 111 implement a simple exclusive access locking mechanism.
 112 If
 113 .Dv O_EXCL
 114 is set and the last component of the pathname is
 115 a symbolic link,
 116 .Fn open
 117 will fail even if the symbolic
 118 link points to a non-existent name.
 119 If the
 120 .Dv O_NONBLOCK
 121 flag is specified and the
 122 .Fn open
 123 call would result
 124 in the process being blocked for some reason (e.g., waiting for
 125 carrier on a dialup line),
 126 .Fn open
 127 returns immediately.
 128 The first time the process attempts to perform I/O on the open
 129 file it will block (not currently implemented).
 130 .Pp
 131 If
 132 .Dv O_FSYNC
 133 is used in the mask, all writes will
 134 immediately be written to disk,
 135 the kernel will not cache written data
 136 and all writes on the descriptor will not return until
 137 the data to be written completes.
 138 .Pp
 139 If
 140 .Dv O_NOFOLLOW
 141 is used in the mask and the target file passed to
 142 .Fn open
 143 is a symbolic link then the
 144 .Fn open
 145 will fail.
 146 .Pp
 147 When opening a file, a lock with
 148 .Xr flock 2
 149 semantics can be obtained by setting
 150 .Dv O_SHLOCK
 151 for a shared lock, or
 152 .Dv O_EXLOCK
 153 for an exclusive lock.
 154 If creating a file with
 155 .Dv O_CREAT ,
 156 the request for the lock will never fail
 157 (provided that the underlying filesystem supports locking).
 158 .Pp
 159 .Dv O_DIRECT
 160 may be used to minimize or eliminate the cache effects of reading and writing.
 161 The system will attempt to avoid caching the data you read or write.
 162 If it cannot avoid caching the data,
 163 it will minimize the impact the data has on the cache.
 164 Use of this flag can drastically reduce performance if not used with care.
 165 .Pp
 166 If successful,
 167 .Fn open
 168 returns a non-negative integer, termed a file descriptor.
 169 It returns -1 on failure.
 170 The file pointer used to mark the current position within the
 171 file is set to the beginning of the file.
 172 .Pp
 173 When a new file is created it is given the group of the directory
 174 which contains it.
 175 .Pp
 176 The new descriptor is set to remain open across
 177 .Xr execve 2
 178 system calls; see
 179 .Xr close 2
 180 and
 181 .Xr fcntl 2 .
 182 .Pp
 183 The system imposes a limit on the number of file descriptors
 184 open simultaneously by one process.
 185 .Xr Getdtablesize 2
 186 returns the current system limit.
 187 .Sh RETURN VALUES
 188 If successful,
 189 .Fn open
 190 returns a non-negative integer, termed a file descriptor.
 191 It returns -1 on failure, and sets
 192 .Va errno
 193 to indicate the error.
 194 .Sh ERRORS
 195 The named file is opened unless:
 196 .Bl -tag -width Er
 197 .It Bq Er ENOTDIR
 198 A component of the path prefix is not a directory.
 199 .It Bq Er ENAMETOOLONG
 200 A component of a pathname exceeded 255 characters,
 201 or an entire path name exceeded 1023 characters.
 202 .It Bq Er ENOENT
 203 .Dv O_CREAT
 204 is not set and the named file does not exist.
 205 .It Bq Er ENOENT
 206 A component of the path name that must exist does not exist.
 207 .It Bq Er EACCES
 208 Search permission is denied for a component of the path prefix.
 209 .It Bq Er EACCES
 210 The required permissions (for reading and/or writing)
 211 are denied for the given flags.
 212 .It Bq Er EACCES
 213 .Dv O_CREAT
 214 is specified,
 215 the file does not exist,
 216 and the directory in which it is to be created
 217 does not permit writing.
 218 .It Bq Er ELOOP
 219 Too many symbolic links were encountered in translating the pathname.
 220 .It Bq Er EISDIR
 221 The named file is a directory, and the arguments specify
 222 it is to be opened for writing.
 223 .It Bq Er EROFS
 224 The named file resides on a read-only file system,
 225 and the file is to be modified.
 226 .It Bq Er EMFILE
 227 The process has already reached its limit for open file descriptors.
 228 .It Bq Er ENFILE
 229 The system file table is full.
 230 .It Bq Er EMLINK
 231 .Dv O_NOFOLLOW
 232 was specified and the target is a symbolic link.
 233 .It Bq Er ENXIO
 234 The named file is a character special or block
 235 special file, and the device associated with this special file
 236 does not exist.
 237 .It Bq Er ENXIO
 238 The named file is a fifo, no process has
 239 it open for reading, and the arguments specify it is
 240 to be opened for writing.
 241 .It Bq Er EINTR
 242 The
 243 .Fn open
 244 operation was interrupted by a signal.
 245 .It Bq Er EOPNOTSUPP
 246 .Dv O_SHLOCK
 247 or
 248 .Dv O_EXLOCK
 249 is specified but the underlying filesystem does not support locking.
 250 .It Bq Er EWOULDBLOCK
 251 .Dv O_NONBLOCK
 252 and one of
 253 .Dv O_SHLOCK
 254 or
 255 .Dv O_EXLOCK
 256 is specified and the file is locked.
 257 .It Bq Er ENOSPC
 258 .Dv O_CREAT
 259 is specified,
 260 the file does not exist,
 261 and the directory in which the entry for the new file is being placed
 262 cannot be extended because there is no space left on the file
 263 system containing the directory.
 264 .It Bq Er ENOSPC
 265 .Dv O_CREAT
 266 is specified,
 267 the file does not exist,
 268 and there are no free inodes on the file system on which the
 269 file is being created.
 270 .It Bq Er EDQUOT
 271 .Dv O_CREAT
 272 is specified,
 273 the file does not exist,
 274 and the directory in which the entry for the new file
 275 is being placed cannot be extended because the
 276 user's quota of disk blocks on the file system
 277 containing the directory has been exhausted.
 278 .It Bq Er EDQUOT
 279 .Dv O_CREAT
 280 is specified,
 281 the file does not exist,
 282 and the user's quota of inodes on the file system on
 283 which the file is being created has been exhausted.
 284 .It Bq Er EIO
 285 An I/O error occurred while making the directory entry or
 286 allocating the inode for
 287 .Dv O_CREAT .
 288 .It Bq Er ETXTBSY
 289 The file is a pure procedure (shared text) file that is being
 290 executed and the
 291 .Fn open
 292 call requests write access.
 293 .It Bq Er EFAULT
 294 .Fa Path
 295 points outside the process's allocated address space.
 296 .It Bq Er EEXIST
 297 .Dv O_CREAT
 298 and
 299 .Dv O_EXCL
 300 were specified and the file exists.
 301 .It Bq Er EOPNOTSUPP
 302 An attempt was made to open a socket (not currently implemented).
 303 .It Bq Er EINVAL
 304 An attempt was made to open a descriptor with an illegal combination
 305 of
 306 .Dv O_RDONLY ,
 307 .Dv O_WRONLY ,
 308 and
 309 .Dv O_RDWR .
 310 .El
 311 .Sh SEE ALSO
 312 .Xr chmod 2 ,
 313 .Xr close 2 ,
 314 .Xr dup 2 ,
 315 .Xr getdtablesize 2 ,
 316 .Xr lseek 2 ,
 317 .Xr read 2 ,
 318 .Xr umask 2 ,
 319 .Xr write 2
 320 .Sh HISTORY
 321 An
 322 .Fn open
 323 function call appeared in
 324 .At v6 .