| 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. |