| 1 |
.\" Copyright 1992, Drew Eckhardt <[email protected]> |
| 2 |
.\" Copyright 2006-2014, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.TH open 2 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
open, openat, creat \- open and possibly create a file |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.B #include <fcntl.h> |
| 16 |
.P |
| 17 |
.BI "int open(const char *" path ", int " flags ", ..." |
| 18 |
.BI " \f[R]/*\f[] mode_t " mode " \f[R]*/\f[] );" |
| 19 |
.P |
| 20 |
.BI "int creat(const char *" path ", mode_t " mode ); |
| 21 |
.P |
| 22 |
.BI "int openat(int " dirfd ", const char *" path ", int " flags ", ..." |
| 23 |
.BI " \f[R]/*\f[] mode_t " mode " \f[R]*/\f[] );" |
| 24 |
.P |
| 25 |
/* Documented separately, in \c |
| 26 |
.BR openat2 (2):\c |
| 27 |
\& */ |
| 28 |
.BI "int openat2(int " dirfd ", const char *" path , |
| 29 |
.BI " const struct open_how *" how ", size_t " size ); |
| 30 |
.fi |
| 31 |
.P |
| 32 |
.RS -4 |
| 33 |
Feature Test Macro Requirements for glibc (see |
| 34 |
.BR feature_test_macros (7)): |
| 35 |
.RE |
| 36 |
.P |
| 37 |
.BR openat (): |
| 38 |
.nf |
| 39 |
Since glibc 2.10: |
| 40 |
_POSIX_C_SOURCE >= 200809L |
| 41 |
Before glibc 2.10: |
| 42 |
_ATFILE_SOURCE |
| 43 |
.fi |
| 44 |
.SH DESCRIPTION |
| 45 |
The |
| 46 |
.BR open () |
| 47 |
system call opens the file specified by |
| 48 |
.IR path . |
| 49 |
If the specified file does not exist, |
| 50 |
it may optionally (if |
| 51 |
.B O_CREAT |
| 52 |
is specified in |
| 53 |
.IR flags ) |
| 54 |
be created by |
| 55 |
.BR open (). |
| 56 |
.P |
| 57 |
The return value of |
| 58 |
.BR open () |
| 59 |
is a file descriptor, a small, nonnegative integer that is an index |
| 60 |
to an entry in the process's table of open file descriptors. |
| 61 |
The file descriptor is used |
| 62 |
in subsequent system calls |
| 63 |
(\c |
| 64 |
.BR read (2), |
| 65 |
.BR write (2), |
| 66 |
.BR lseek (2), |
| 67 |
.BR fcntl (2), |
| 68 |
etc.) |
| 69 |
to refer to the open file. |
| 70 |
The file descriptor returned by a successful call will be |
| 71 |
the lowest-numbered file descriptor not currently open for the process. |
| 72 |
.P |
| 73 |
By default, the new file descriptor is set to remain open across an |
| 74 |
.BR execve (2) |
| 75 |
(i.e., the |
| 76 |
.B FD_CLOEXEC |
| 77 |
file descriptor flag described in |
| 78 |
.BR fcntl (2) |
| 79 |
is initially disabled); |
| 80 |
the |
| 81 |
.B O_CLOEXEC |
| 82 |
flag, described below, can be used to change this default. |
| 83 |
The file offset is set to the beginning of the file (see |
| 84 |
.BR lseek (2)). |
| 85 |
.P |
| 86 |
A call to |
| 87 |
.BR open () |
| 88 |
creates a new |
| 89 |
.IR "open file description" , |
| 90 |
an entry in the system-wide table of open files. |
| 91 |
The open file description records the file offset and the file status flags |
| 92 |
(see below). |
| 93 |
A file descriptor is a reference to an open file description; |
| 94 |
this reference is unaffected if |
| 95 |
.I path |
| 96 |
is subsequently removed or modified to refer to a different file. |
| 97 |
For further details on open file descriptions, see NOTES. |
| 98 |
.P |
| 99 |
The argument |
| 100 |
.I flags |
| 101 |
must include one of the following |
| 102 |
.IR "access modes" : |
| 103 |
.BR O_RDONLY ", " O_WRONLY ", or " O_RDWR . |
| 104 |
These request opening the file read-only, write-only, or read/write, |
| 105 |
respectively. |
| 106 |
.P |
| 107 |
In addition, zero or more file creation flags and file status flags |
| 108 |
can be |
| 109 |
bitwise ORed |
| 110 |
in |
| 111 |
.IR flags . |
| 112 |
The |
| 113 |
.I file creation flags |
| 114 |
are |
| 115 |
.BR O_CLOEXEC , |
| 116 |
.BR O_CREAT , |
| 117 |
.BR O_DIRECTORY , |
| 118 |
.BR O_EXCL , |
| 119 |
.BR O_NOCTTY , |
| 120 |
.BR O_NOFOLLOW , |
| 121 |
.BR O_TMPFILE , |
| 122 |
and |
| 123 |
.BR O_TRUNC . |
| 124 |
The |
| 125 |
.I file status flags |
| 126 |
are all of the remaining flags listed below. |
| 127 |
.\" SUSv4 divides the flags into: |
| 128 |
.\" * Access mode |
| 129 |
.\" * File creation |
| 130 |
.\" * File status |
| 131 |
.\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW) |
| 132 |
.\" though it's not clear what the difference between "other" and |
| 133 |
.\" "File creation" flags is. I raised an Aardvark to see if this |
| 134 |
.\" can be clarified in SUSv4; 10 Oct 2008. |
| 135 |
.\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67 |
| 136 |
.\" TC1 (balloted in 2013), resolved this, so that those three constants |
| 137 |
.\" are also categorized" as file status flags. |
| 138 |
.\" |
| 139 |
The distinction between these two groups of flags is that |
| 140 |
the file creation flags affect the semantics of the open operation itself, |
| 141 |
while the file status flags affect the semantics of subsequent I/O operations. |
| 142 |
The file status flags can be retrieved and (in some cases) |
| 143 |
modified; |
| 144 |
see |
| 145 |
.BR fcntl (2) |
| 146 |
for details. |
| 147 |
.P |
| 148 |
The full list of file creation flags and file status flags is as follows: |
| 149 |
.TP |
| 150 |
.B O_APPEND |
| 151 |
The file is opened in append mode. |
| 152 |
Before each |
| 153 |
.BR write (2), |
| 154 |
the file offset is positioned at the end of the file, |
| 155 |
as if with |
| 156 |
.BR lseek (2). |
| 157 |
The modification of the file offset and the write operation |
| 158 |
are performed as a single atomic step. |
| 159 |
.IP |
| 160 |
.B O_APPEND |
| 161 |
may lead to corrupted files on NFS filesystems if more than one process |
| 162 |
appends data to a file at once. |
| 163 |
.\" For more background, see |
| 164 |
.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946 |
| 165 |
.\" http://nfs.sourceforge.net/ |
| 166 |
This is because NFS does not support |
| 167 |
appending to a file, so the client kernel has to simulate it, which |
| 168 |
can't be done without a race condition. |
| 169 |
.TP |
| 170 |
.B O_ASYNC |
| 171 |
Enable signal-driven I/O: |
| 172 |
generate a signal |
| 173 |
.RB ( SIGIO |
| 174 |
by default, but this can be changed via |
| 175 |
.BR fcntl (2)) |
| 176 |
when input or output becomes possible on this file descriptor. |
| 177 |
This feature is available only for terminals, pseudoterminals, |
| 178 |
sockets, and (since Linux 2.6) pipes and FIFOs. |
| 179 |
See |
| 180 |
.BR fcntl (2) |
| 181 |
for further details. |
| 182 |
See also BUGS, below. |
| 183 |
.TP |
| 184 |
.BR O_CLOEXEC " (since Linux 2.6.23)" |
| 185 |
.\" NOTE! several other man pages refer to this text |
| 186 |
Enable the close-on-exec flag for the new file descriptor. |
| 187 |
.\" FIXME . for later review when Issue 8 is one day released... |
| 188 |
.\" POSIX proposes to fix many APIs that provide hidden FDs |
| 189 |
.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 |
| 190 |
.\" http://austingroupbugs.net/view.php?id=368 |
| 191 |
Specifying this flag permits a program to avoid additional |
| 192 |
.BR fcntl (2) |
| 193 |
.B F_SETFD |
| 194 |
operations to set the |
| 195 |
.B FD_CLOEXEC |
| 196 |
flag. |
| 197 |
.IP |
| 198 |
Note that the use of this flag is essential in some multithreaded programs, |
| 199 |
because using a separate |
| 200 |
.BR fcntl (2) |
| 201 |
.B F_SETFD |
| 202 |
operation to set the |
| 203 |
.B FD_CLOEXEC |
| 204 |
flag does not suffice to avoid race conditions |
| 205 |
where one thread opens a file descriptor and |
| 206 |
attempts to set its close-on-exec flag using |
| 207 |
.BR fcntl (2) |
| 208 |
at the same time as another thread does a |
| 209 |
.BR fork (2) |
| 210 |
plus |
| 211 |
.BR execve (2). |
| 212 |
Depending on the order of execution, |
| 213 |
the race may lead to the file descriptor returned by |
| 214 |
.BR open () |
| 215 |
being unintentionally leaked to the program executed by the child process |
| 216 |
created by |
| 217 |
.BR fork (2). |
| 218 |
(This kind of race is in principle possible for any system call |
| 219 |
that creates a file descriptor whose close-on-exec flag should be set, |
| 220 |
and various other Linux system calls provide an equivalent of the |
| 221 |
.B O_CLOEXEC |
| 222 |
flag to deal with this problem.) |
| 223 |
.\" This flag fixes only one form of the race condition; |
| 224 |
.\" The race can also occur with, for example, file descriptors |
| 225 |
.\" returned by accept(), pipe(), etc. |
| 226 |
.TP |
| 227 |
.B O_CREAT |
| 228 |
If |
| 229 |
.I path |
| 230 |
does not exist, create it as a regular file. |
| 231 |
.IP |
| 232 |
The owner (user ID) of the new file is set to the effective user ID |
| 233 |
of the process. |
| 234 |
.IP |
| 235 |
The group ownership (group ID) of the new file is set either to |
| 236 |
the effective group ID of the process (System V semantics) |
| 237 |
or to the group ID of the parent directory (BSD semantics). |
| 238 |
On Linux, the behavior depends on whether the |
| 239 |
set-group-ID mode bit is set on the parent directory: |
| 240 |
if that bit is set, then BSD semantics apply; |
| 241 |
otherwise, System V semantics apply. |
| 242 |
For some filesystems, the behavior also depends on the |
| 243 |
.I bsdgroups |
| 244 |
and |
| 245 |
.I sysvgroups |
| 246 |
mount options described in |
| 247 |
.BR mount (8). |
| 248 |
.\" As at Linux 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and |
| 249 |
.\" XFS (since Linux 2.6.14). |
| 250 |
.IP |
| 251 |
The |
| 252 |
.I mode |
| 253 |
argument specifies the file mode bits to be applied when a new file is created. |
| 254 |
If neither |
| 255 |
.B O_CREAT |
| 256 |
nor |
| 257 |
.B O_TMPFILE |
| 258 |
is specified in |
| 259 |
.IR flags , |
| 260 |
then |
| 261 |
.I mode |
| 262 |
is ignored (and can thus be specified as 0, or simply omitted). |
| 263 |
The |
| 264 |
.I mode |
| 265 |
argument |
| 266 |
.B must |
| 267 |
be supplied if |
| 268 |
.B O_CREAT |
| 269 |
or |
| 270 |
.B O_TMPFILE |
| 271 |
is specified in |
| 272 |
.IR flags ; |
| 273 |
if it is not supplied, |
| 274 |
some arbitrary bytes from the stack will be applied as the file mode. |
| 275 |
.IP |
| 276 |
The effective mode is modified by the process's |
| 277 |
.I umask |
| 278 |
in the usual way: in the absence of a default ACL, the mode of the |
| 279 |
created file is |
| 280 |
.IR "(mode\ &\ \[ti]umask)" . |
| 281 |
.IP |
| 282 |
Note that |
| 283 |
.I mode |
| 284 |
applies only to future accesses of the |
| 285 |
newly created file; |
| 286 |
the |
| 287 |
.BR open () |
| 288 |
call that creates a read-only file |
| 289 |
may well return a read/write file descriptor. |
| 290 |
.IP |
| 291 |
The following symbolic constants are provided for |
| 292 |
.IR mode : |
| 293 |
.RS |
| 294 |
.TP 9 |
| 295 |
.B S_IRWXU |
| 296 |
00700 user (file owner) has read, write, and execute permission |
| 297 |
.TP |
| 298 |
.B S_IRUSR |
| 299 |
00400 user has read permission |
| 300 |
.TP |
| 301 |
.B S_IWUSR |
| 302 |
00200 user has write permission |
| 303 |
.TP |
| 304 |
.B S_IXUSR |
| 305 |
00100 user has execute permission |
| 306 |
.TP |
| 307 |
.B S_IRWXG |
| 308 |
00070 group has read, write, and execute permission |
| 309 |
.TP |
| 310 |
.B S_IRGRP |
| 311 |
00040 group has read permission |
| 312 |
.TP |
| 313 |
.B S_IWGRP |
| 314 |
00020 group has write permission |
| 315 |
.TP |
| 316 |
.B S_IXGRP |
| 317 |
00010 group has execute permission |
| 318 |
.TP |
| 319 |
.B S_IRWXO |
| 320 |
00007 others have read, write, and execute permission |
| 321 |
.TP |
| 322 |
.B S_IROTH |
| 323 |
00004 others have read permission |
| 324 |
.TP |
| 325 |
.B S_IWOTH |
| 326 |
00002 others have write permission |
| 327 |
.TP |
| 328 |
.B S_IXOTH |
| 329 |
00001 others have execute permission |
| 330 |
.RE |
| 331 |
.IP |
| 332 |
According to POSIX, the effect when other bits are set in |
| 333 |
.I mode |
| 334 |
is unspecified. |
| 335 |
On Linux, the following bits are also honored in |
| 336 |
.IR mode : |
| 337 |
.RS |
| 338 |
.TP 9 |
| 339 |
.B S_ISUID |
| 340 |
0004000 set-user-ID bit |
| 341 |
.TP |
| 342 |
.B S_ISGID |
| 343 |
0002000 set-group-ID bit (see |
| 344 |
.BR inode (7)). |
| 345 |
.TP |
| 346 |
.B S_ISVTX |
| 347 |
0001000 sticky bit (see |
| 348 |
.BR inode (7)). |
| 349 |
.RE |
| 350 |
.TP |
| 351 |
.BR O_DIRECT " (since Linux 2.4.10)" |
| 352 |
Try to minimize cache effects of the I/O to and from this file. |
| 353 |
In general this will degrade performance, but it is useful in |
| 354 |
special situations, such as when applications do their own caching. |
| 355 |
File I/O is done directly to/from user-space buffers. |
| 356 |
The |
| 357 |
.B O_DIRECT |
| 358 |
flag on its own makes an effort to transfer data synchronously, |
| 359 |
but does not give the guarantees of the |
| 360 |
.B O_SYNC |
| 361 |
flag that data and necessary metadata are transferred. |
| 362 |
To guarantee synchronous I/O, |
| 363 |
.B O_SYNC |
| 364 |
must be used in addition to |
| 365 |
.BR O_DIRECT . |
| 366 |
See NOTES below for further discussion. |
| 367 |
.IP |
| 368 |
A semantically similar (but deprecated) interface for block devices |
| 369 |
is described in |
| 370 |
.BR raw (8). |
| 371 |
.TP |
| 372 |
.B O_DIRECTORY |
| 373 |
If |
| 374 |
.I path |
| 375 |
is not a directory, |
| 376 |
cause |
| 377 |
.BR open () |
| 378 |
to fail. |
| 379 |
.\" But see the following and its replies: |
| 380 |
.\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2 |
| 381 |
.\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail |
| 382 |
.\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored. |
| 383 |
This flag was added in Linux 2.1.126, to |
| 384 |
avoid denial-of-service problems if |
| 385 |
.BR opendir (3) |
| 386 |
is called on a |
| 387 |
FIFO or tape device. |
| 388 |
.TP |
| 389 |
.B O_DSYNC |
| 390 |
Write operations on the file will complete according to the requirements of |
| 391 |
synchronized I/O |
| 392 |
.I data |
| 393 |
integrity completion. |
| 394 |
.IP |
| 395 |
By the time |
| 396 |
.BR write (2) |
| 397 |
(and similar) |
| 398 |
return, the output data |
| 399 |
has been transferred to the underlying hardware, |
| 400 |
along with any file metadata that would be required to retrieve that data |
| 401 |
(i.e., as though each |
| 402 |
.BR write (2) |
| 403 |
was followed by a call to |
| 404 |
.BR fdatasync (2)). |
| 405 |
See VERSIONS. |
| 406 |
.TP |
| 407 |
.B O_EXCL |
| 408 |
Ensure that this call creates the file: |
| 409 |
if this flag is specified in conjunction with |
| 410 |
.BR O_CREAT , |
| 411 |
and |
| 412 |
.I path |
| 413 |
already exists, then |
| 414 |
.BR open () |
| 415 |
fails with the error |
| 416 |
.BR EEXIST . |
| 417 |
.IP |
| 418 |
When these two flags are specified, symbolic links are not followed: |
| 419 |
.\" POSIX.1-2001 explicitly requires this behavior. |
| 420 |
if |
| 421 |
.I path |
| 422 |
is a symbolic link, then |
| 423 |
.BR open () |
| 424 |
fails regardless of where the symbolic link points. |
| 425 |
.IP |
| 426 |
In general, the behavior of |
| 427 |
.B O_EXCL |
| 428 |
is undefined if it is used without |
| 429 |
.BR O_CREAT . |
| 430 |
There is one exception: on Linux 2.6 and later, |
| 431 |
.B O_EXCL |
| 432 |
can be used without |
| 433 |
.B O_CREAT |
| 434 |
if |
| 435 |
.I path |
| 436 |
refers to a block device. |
| 437 |
If the block device is in use by the system (e.g., mounted), |
| 438 |
.BR open () |
| 439 |
fails with the error |
| 440 |
.BR EBUSY . |
| 441 |
.IP |
| 442 |
On NFS, |
| 443 |
.B O_EXCL |
| 444 |
is supported only when using NFSv3 or later on kernel 2.6 or later. |
| 445 |
In NFS environments where |
| 446 |
.B O_EXCL |
| 447 |
support is not provided, programs that rely on it |
| 448 |
for performing locking tasks will contain a race condition. |
| 449 |
Portable programs that want to perform atomic file locking using a lockfile, |
| 450 |
and need to avoid reliance on NFS support for |
| 451 |
.BR O_EXCL , |
| 452 |
can create a unique file on |
| 453 |
the same filesystem (e.g., incorporating hostname and PID), and use |
| 454 |
.BR link (2) |
| 455 |
to make a link to the lockfile. |
| 456 |
If |
| 457 |
.BR link (2) |
| 458 |
returns 0, the lock is successful. |
| 459 |
Otherwise, use |
| 460 |
.BR stat (2) |
| 461 |
on the unique file to check if its link count has increased to 2, |
| 462 |
in which case the lock is also successful. |
| 463 |
.TP |
| 464 |
.B O_LARGEFILE |
| 465 |
(LFS) |
| 466 |
Allow files whose sizes cannot be represented in an |
| 467 |
.I off_t |
| 468 |
(but can be represented in an |
| 469 |
.IR off64_t ) |
| 470 |
to be opened. |
| 471 |
The |
| 472 |
.B _LARGEFILE64_SOURCE |
| 473 |
macro must be defined |
| 474 |
(before including |
| 475 |
.I any |
| 476 |
header files) |
| 477 |
in order to obtain this definition. |
| 478 |
Setting the |
| 479 |
.B _FILE_OFFSET_BITS |
| 480 |
feature test macro to 64 (rather than using |
| 481 |
.BR O_LARGEFILE ) |
| 482 |
is the preferred |
| 483 |
method of accessing large files on 32-bit systems (see |
| 484 |
.BR feature_test_macros (7)). |
| 485 |
.TP |
| 486 |
.BR O_NOATIME " (since Linux 2.6.8)" |
| 487 |
Do not update the file last access time |
| 488 |
.RI ( st_atime |
| 489 |
in the inode) |
| 490 |
when the file is |
| 491 |
.BR read (2). |
| 492 |
.IP |
| 493 |
This flag can be employed only if one of the following conditions is true: |
| 494 |
.RS |
| 495 |
.IP \[bu] 3 |
| 496 |
The effective UID of the process |
| 497 |
.\" Strictly speaking: the filesystem UID |
| 498 |
matches the owner UID of the file. |
| 499 |
.IP \[bu] |
| 500 |
The calling process has the |
| 501 |
.B CAP_FOWNER |
| 502 |
capability in its user namespace and |
| 503 |
the owner UID of the file has a mapping in the namespace. |
| 504 |
.RE |
| 505 |
.IP |
| 506 |
This flag is intended for use by indexing or backup programs, |
| 507 |
where its use can significantly reduce the amount of disk activity. |
| 508 |
This flag may not be effective on all filesystems. |
| 509 |
One example is NFS, where the server maintains the access time. |
| 510 |
.\" The O_NOATIME flag also affects the treatment of st_atime |
| 511 |
.\" by mmap() and readdir(2), MTK, Dec 04. |
| 512 |
.TP |
| 513 |
.B O_NOCTTY |
| 514 |
If |
| 515 |
.I path |
| 516 |
refers to a terminal device\[em]see |
| 517 |
.BR tty (4)\[em]it |
| 518 |
will not become the process's controlling terminal even if the |
| 519 |
process does not have one. |
| 520 |
.TP |
| 521 |
.B O_NOFOLLOW |
| 522 |
If the trailing component (i.e., basename) of |
| 523 |
.I path |
| 524 |
is a symbolic link, then the open fails, with the error |
| 525 |
.BR ELOOP . |
| 526 |
Symbolic links in earlier components of the pathname will still be |
| 527 |
followed. |
| 528 |
(Note that the |
| 529 |
.B ELOOP |
| 530 |
error that can occur in this case is indistinguishable from the case where |
| 531 |
an open fails because there are too many symbolic links found |
| 532 |
while resolving components in the path prefix of the pathname.) |
| 533 |
.IP |
| 534 |
This flag is a FreeBSD extension, which was added in Linux 2.1.126, |
| 535 |
and has subsequently been standardized in POSIX.1-2008. |
| 536 |
.IP |
| 537 |
See also |
| 538 |
.B O_PATH |
| 539 |
below. |
| 540 |
.\" The headers from glibc 2.0.100 and later include a |
| 541 |
.\" definition of this flag; \f[I]kernels before Linux 2.1.126 will ignore it if |
| 542 |
.\" used\f[]. |
| 543 |
.TP |
| 544 |
.BR O_NONBLOCK " or " O_NDELAY |
| 545 |
When possible, the file is opened in nonblocking mode. |
| 546 |
Neither the |
| 547 |
.BR open () |
| 548 |
nor any subsequent I/O operations on the file descriptor which is |
| 549 |
returned will cause the calling process to wait. |
| 550 |
.IP |
| 551 |
Note that the setting of this flag has no effect on the operation of |
| 552 |
.BR poll (2), |
| 553 |
.BR select (2), |
| 554 |
.BR epoll (7), |
| 555 |
and similar, |
| 556 |
since those interfaces merely inform the caller about whether |
| 557 |
a file descriptor is "ready", |
| 558 |
meaning that an I/O operation performed on |
| 559 |
the file descriptor with the |
| 560 |
.B O_NONBLOCK |
| 561 |
flag |
| 562 |
.I clear |
| 563 |
would not block. |
| 564 |
.IP |
| 565 |
Note that this flag has no effect for regular files and block devices; |
| 566 |
that is, I/O operations will (briefly) block when device activity |
| 567 |
is required, regardless of whether |
| 568 |
.B O_NONBLOCK |
| 569 |
is set. |
| 570 |
Since |
| 571 |
.B O_NONBLOCK |
| 572 |
semantics might eventually be implemented, |
| 573 |
applications should not depend upon blocking behavior |
| 574 |
when specifying this flag for regular files and block devices. |
| 575 |
.IP |
| 576 |
For the handling of FIFOs (named pipes), see also |
| 577 |
.BR fifo (7). |
| 578 |
For a discussion of the effect of |
| 579 |
.B O_NONBLOCK |
| 580 |
in conjunction with mandatory file locks and with file leases, see |
| 581 |
.BR fcntl (2). |
| 582 |
.TP |
| 583 |
.BR O_PATH " (since Linux 2.6.39)" |
| 584 |
.\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd |
| 585 |
.\" commit 326be7b484843988afe57566b627fb7a70beac56 |
| 586 |
.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d |
| 587 |
.\" |
| 588 |
.\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496 |
| 589 |
.\" Subject: Re: [PATCH] open(2): document O_PATH |
| 590 |
.\" Newsgroups: gmane.linux.man, gmane.linux.kernel |
| 591 |
.\" |
| 592 |
Obtain a file descriptor that can be used for two purposes: |
| 593 |
to indicate a location in the filesystem tree and |
| 594 |
to perform operations that act purely at the file descriptor level. |
| 595 |
The file itself is not opened, and other file operations (e.g., |
| 596 |
.BR read (2), |
| 597 |
.BR write (2), |
| 598 |
.BR fchmod (2), |
| 599 |
.BR fchown (2), |
| 600 |
.BR fgetxattr (2), |
| 601 |
.BR ioctl (2), |
| 602 |
.BR mmap (2)) |
| 603 |
fail with the error |
| 604 |
.BR EBADF . |
| 605 |
.IP |
| 606 |
The following operations |
| 607 |
.I can |
| 608 |
be performed on the resulting file descriptor: |
| 609 |
.RS |
| 610 |
.IP \[bu] 3 |
| 611 |
.BR close (2). |
| 612 |
.IP \[bu] |
| 613 |
.BR fchdir (2), |
| 614 |
if the file descriptor refers to a directory |
| 615 |
(since Linux 3.5). |
| 616 |
.\" commit 332a2e1244bd08b9e3ecd378028513396a004a24 |
| 617 |
.IP \[bu] |
| 618 |
.BR fstat (2) |
| 619 |
(since Linux 3.6). |
| 620 |
.IP \[bu] |
| 621 |
.\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2 |
| 622 |
.BR fstatfs (2) |
| 623 |
(since Linux 3.12). |
| 624 |
.\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf |
| 625 |
.IP \[bu] |
| 626 |
Duplicating the file descriptor |
| 627 |
.RB ( dup (2), |
| 628 |
.BR fcntl (2) |
| 629 |
.BR F_DUPFD , |
| 630 |
etc.). |
| 631 |
.IP \[bu] |
| 632 |
Getting and setting file descriptor flags |
| 633 |
.RB ( fcntl (2) |
| 634 |
.B F_GETFD |
| 635 |
and |
| 636 |
.BR F_SETFD ). |
| 637 |
.IP \[bu] |
| 638 |
Retrieving open file status flags using the |
| 639 |
.BR fcntl (2) |
| 640 |
.B F_GETFL |
| 641 |
operation: the returned flags will include the bit |
| 642 |
.BR O_PATH . |
| 643 |
.IP \[bu] |
| 644 |
Passing the file descriptor as the |
| 645 |
.I dirfd |
| 646 |
argument of |
| 647 |
.BR openat () |
| 648 |
and the other "*at()" system calls. |
| 649 |
This includes |
| 650 |
.BR linkat (2) |
| 651 |
with |
| 652 |
.B AT_EMPTY_PATH |
| 653 |
(or via procfs using |
| 654 |
.BR AT_SYMLINK_FOLLOW ) |
| 655 |
even if the file is not a directory. |
| 656 |
.IP \[bu] |
| 657 |
Passing the file descriptor to another process via a UNIX domain socket |
| 658 |
(see |
| 659 |
.B SCM_RIGHTS |
| 660 |
in |
| 661 |
.BR unix (7)). |
| 662 |
.RE |
| 663 |
.IP |
| 664 |
When |
| 665 |
.B O_PATH |
| 666 |
is specified in |
| 667 |
.IR flags , |
| 668 |
flag bits other than |
| 669 |
.BR O_CLOEXEC , |
| 670 |
.BR O_DIRECTORY , |
| 671 |
and |
| 672 |
.B O_NOFOLLOW |
| 673 |
are ignored. |
| 674 |
.IP |
| 675 |
Opening a file or directory with the |
| 676 |
.B O_PATH |
| 677 |
flag requires no permissions on the object itself |
| 678 |
(but does require execute permission on the directories in the path prefix). |
| 679 |
Depending on the subsequent operation, |
| 680 |
a check for suitable file permissions may be performed (e.g., |
| 681 |
.BR fchdir (2) |
| 682 |
requires execute permission on the directory referred to |
| 683 |
by its file descriptor argument). |
| 684 |
By contrast, |
| 685 |
obtaining a reference to a filesystem object by opening it with the |
| 686 |
.B O_RDONLY |
| 687 |
flag requires that the caller have read permission on the object, |
| 688 |
even when the subsequent operation (e.g., |
| 689 |
.BR fchdir (2), |
| 690 |
.BR fstat (2)) |
| 691 |
does not require read permission on the object. |
| 692 |
.IP |
| 693 |
If |
| 694 |
.I path |
| 695 |
is a symbolic link and the |
| 696 |
.B O_NOFOLLOW |
| 697 |
flag is also specified, |
| 698 |
then the call returns a file descriptor referring to the symbolic link. |
| 699 |
This file descriptor can be used as the |
| 700 |
.I dirfd |
| 701 |
argument in calls to |
| 702 |
.BR fchownat (2), |
| 703 |
.BR fstatat (2), |
| 704 |
.BR linkat (2), |
| 705 |
and |
| 706 |
.BR readlinkat (2) |
| 707 |
with an empty pathname to have the calls operate on the symbolic link. |
| 708 |
.IP |
| 709 |
If |
| 710 |
.I path |
| 711 |
refers to an automount point that has not yet been triggered, so no |
| 712 |
other filesystem is mounted on it, then the call returns a file |
| 713 |
descriptor referring to the automount directory without triggering a mount. |
| 714 |
.BR fstatfs (2) |
| 715 |
can then be used to determine if it is, in fact, an untriggered |
| 716 |
automount point |
| 717 |
.RB ( ".f_type == AUTOFS_SUPER_MAGIC" ). |
| 718 |
.IP |
| 719 |
One use of |
| 720 |
.B O_PATH |
| 721 |
for regular files is to provide the equivalent of POSIX.1's |
| 722 |
.B O_EXEC |
| 723 |
functionality. |
| 724 |
This permits us to open a file for which we have execute |
| 725 |
permission but not read permission, and then execute that file, |
| 726 |
with steps something like the following: |
| 727 |
.IP |
| 728 |
.in +4n |
| 729 |
.EX |
| 730 |
char buf[PATH_MAX]; |
| 731 |
fd = open("some_prog", O_PATH); |
| 732 |
snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd); |
| 733 |
execl(buf, "some_prog", (char *) NULL); |
| 734 |
.EE |
| 735 |
.in |
| 736 |
.IP |
| 737 |
An |
| 738 |
.B O_PATH |
| 739 |
file descriptor can also be passed as the argument of |
| 740 |
.BR fexecve (3). |
| 741 |
.TP |
| 742 |
.B O_SYNC |
| 743 |
Write operations on the file will complete according to the requirements of |
| 744 |
synchronized I/O |
| 745 |
.I file |
| 746 |
integrity completion |
| 747 |
(by contrast with the |
| 748 |
synchronized I/O |
| 749 |
.I data |
| 750 |
integrity completion |
| 751 |
provided by |
| 752 |
.BR O_DSYNC .) |
| 753 |
.IP |
| 754 |
By the time |
| 755 |
.BR write (2) |
| 756 |
(or similar) |
| 757 |
returns, the output data and associated file metadata |
| 758 |
have been transferred to the underlying hardware |
| 759 |
(i.e., as though each |
| 760 |
.BR write (2) |
| 761 |
was followed by a call to |
| 762 |
.BR fsync (2)). |
| 763 |
See VERSIONS. |
| 764 |
.TP |
| 765 |
.BR O_TMPFILE " (since Linux 3.11)" |
| 766 |
.\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e |
| 767 |
.\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e |
| 768 |
.\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd |
| 769 |
Create an unnamed temporary regular file. |
| 770 |
The |
| 771 |
.I path |
| 772 |
argument specifies a directory; |
| 773 |
an unnamed inode will be created in that directory's filesystem. |
| 774 |
Anything written to the resulting file will be lost when |
| 775 |
the last file descriptor is closed, unless the file is given a name. |
| 776 |
.IP |
| 777 |
.B O_TMPFILE |
| 778 |
must be specified with one of |
| 779 |
.B O_RDWR |
| 780 |
or |
| 781 |
.B O_WRONLY |
| 782 |
and, optionally, |
| 783 |
.BR O_EXCL . |
| 784 |
If |
| 785 |
.B O_EXCL |
| 786 |
is not specified, then |
| 787 |
.BR linkat (2) |
| 788 |
can be used to link the temporary file into the filesystem, making it |
| 789 |
permanent, using code like the following: |
| 790 |
.IP |
| 791 |
.in +4n |
| 792 |
.EX |
| 793 |
char path[PATH_MAX]; |
| 794 |
fd = open("/path/to/dir", O_TMPFILE | O_RDWR, |
| 795 |
S_IRUSR | S_IWUSR); |
| 796 |
\& |
| 797 |
/* File I/O on \[aq]fd\[aq]... */ |
| 798 |
\& |
| 799 |
linkat(fd, "", AT_FDCWD, "/path/for/file", AT_EMPTY_PATH); |
| 800 |
\& |
| 801 |
/* If the caller doesn\[aq]t have the CAP_DAC_READ_SEARCH |
| 802 |
capability (needed to use AT_EMPTY_PATH with linkat(2)), |
| 803 |
and there is a proc(5) filesystem mounted, then the |
| 804 |
linkat(2) call above can be replaced with: |
| 805 |
\& |
| 806 |
snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd); |
| 807 |
linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file", |
| 808 |
AT_SYMLINK_FOLLOW); |
| 809 |
*/ |
| 810 |
.EE |
| 811 |
.in |
| 812 |
.IP |
| 813 |
In this case, |
| 814 |
the |
| 815 |
.BR open () |
| 816 |
.I mode |
| 817 |
argument determines the file permission mode, as with |
| 818 |
.BR O_CREAT . |
| 819 |
.IP |
| 820 |
Specifying |
| 821 |
.B O_EXCL |
| 822 |
in conjunction with |
| 823 |
.B O_TMPFILE |
| 824 |
prevents a temporary file from being linked into the filesystem |
| 825 |
in the above manner. |
| 826 |
(Note that the meaning of |
| 827 |
.B O_EXCL |
| 828 |
in this case is different from the meaning of |
| 829 |
.B O_EXCL |
| 830 |
otherwise.) |
| 831 |
.IP |
| 832 |
There are two main use cases for |
| 833 |
.\" Inspired by http://lwn.net/Articles/559147/ |
| 834 |
.BR O_TMPFILE : |
| 835 |
.RS |
| 836 |
.IP \[bu] 3 |
| 837 |
Improved |
| 838 |
.BR tmpfile (3) |
| 839 |
functionality: race-free creation of temporary files that |
| 840 |
(1) are automatically deleted when closed; |
| 841 |
(2) can never be reached via any pathname; |
| 842 |
(3) are not subject to symlink attacks; |
| 843 |
and |
| 844 |
(4) do not require the caller to devise unique names. |
| 845 |
.IP \[bu] |
| 846 |
Creating a file that is initially invisible, which is then populated |
| 847 |
with data and adjusted to have appropriate filesystem attributes |
| 848 |
.RB ( fchown (2), |
| 849 |
.BR fchmod (2), |
| 850 |
.BR fsetxattr (2), |
| 851 |
etc.) |
| 852 |
before being atomically linked into the filesystem |
| 853 |
in a fully formed state (using |
| 854 |
.BR linkat (2) |
| 855 |
as described above). |
| 856 |
.RE |
| 857 |
.IP |
| 858 |
.B O_TMPFILE |
| 859 |
requires support by the underlying filesystem; |
| 860 |
only a subset of Linux filesystems provide that support. |
| 861 |
In the initial implementation, support was provided in |
| 862 |
the ext2, ext3, ext4, UDF, Minix, and tmpfs filesystems. |
| 863 |
.\" To check for support, grep for "tmpfile" in kernel sources |
| 864 |
Support for other filesystems has subsequently been added as follows: |
| 865 |
XFS (Linux 3.15); |
| 866 |
.\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788 |
| 867 |
.\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe |
| 868 |
Btrfs (Linux 3.16); |
| 869 |
.\" commit ef3b9af50bfa6a1f02cd7b3f5124b712b1ba3e3c |
| 870 |
F2FS (Linux 3.16); |
| 871 |
.\" commit 50732df02eefb39ab414ef655979c2c9b64ad21c |
| 872 |
and ubifs (Linux 4.9) |
| 873 |
.TP |
| 874 |
.B O_TRUNC |
| 875 |
If the file already exists and is a regular file and the access mode allows |
| 876 |
writing (i.e., is |
| 877 |
.B O_RDWR |
| 878 |
or |
| 879 |
.BR O_WRONLY ) |
| 880 |
it will be truncated to length 0. |
| 881 |
If the file is a FIFO or terminal device file, the |
| 882 |
.B O_TRUNC |
| 883 |
flag is ignored. |
| 884 |
Otherwise, the effect of |
| 885 |
.B O_TRUNC |
| 886 |
is unspecified. |
| 887 |
.SS creat() |
| 888 |
A call to |
| 889 |
.BR creat () |
| 890 |
is equivalent to calling |
| 891 |
.BR open () |
| 892 |
with |
| 893 |
.I flags |
| 894 |
equal to |
| 895 |
.BR O_CREAT|O_WRONLY|O_TRUNC . |
| 896 |
.SS openat() |
| 897 |
The |
| 898 |
.BR openat () |
| 899 |
system call operates in exactly the same way as |
| 900 |
.BR open (), |
| 901 |
except for the differences described here. |
| 902 |
.P |
| 903 |
The |
| 904 |
.I dirfd |
| 905 |
argument is used in conjunction with the |
| 906 |
.I path |
| 907 |
argument as follows: |
| 908 |
.IP \[bu] 3 |
| 909 |
If the pathname given in |
| 910 |
.I path |
| 911 |
is absolute, then |
| 912 |
.I dirfd |
| 913 |
is ignored. |
| 914 |
.IP \[bu] |
| 915 |
If the pathname given in |
| 916 |
.I path |
| 917 |
is relative and |
| 918 |
.I dirfd |
| 919 |
is the special value |
| 920 |
.BR AT_FDCWD , |
| 921 |
then |
| 922 |
.I path |
| 923 |
is interpreted relative to the current working |
| 924 |
directory of the calling process (like |
| 925 |
.BR open ()). |
| 926 |
.IP \[bu] |
| 927 |
If the pathname given in |
| 928 |
.I path |
| 929 |
is relative, then it is interpreted relative to the directory |
| 930 |
referred to by the file descriptor |
| 931 |
.I dirfd |
| 932 |
(rather than relative to the current working directory of |
| 933 |
the calling process, as is done by |
| 934 |
.BR open () |
| 935 |
for a relative pathname). |
| 936 |
In this case, |
| 937 |
.I dirfd |
| 938 |
must be a directory that was opened for reading |
| 939 |
.RB ( O_RDONLY ) |
| 940 |
or using the |
| 941 |
.B O_PATH |
| 942 |
flag. |
| 943 |
.P |
| 944 |
If the pathname given in |
| 945 |
.I path |
| 946 |
is relative, and |
| 947 |
.I dirfd |
| 948 |
is not a valid file descriptor, an error |
| 949 |
.RB ( EBADF ) |
| 950 |
results. |
| 951 |
(Specifying an invalid file descriptor number in |
| 952 |
.I dirfd |
| 953 |
can be used as a means to ensure that |
| 954 |
.I path |
| 955 |
is absolute.) |
| 956 |
.\" |
| 957 |
.SS openat2(2) |
| 958 |
The |
| 959 |
.BR openat2 (2) |
| 960 |
system call is an extension of |
| 961 |
.BR openat (), |
| 962 |
and provides a superset of the features of |
| 963 |
.BR openat (). |
| 964 |
It is documented separately, in |
| 965 |
.BR openat2 (2). |
| 966 |
.SH RETURN VALUE |
| 967 |
On success, |
| 968 |
.BR open (), |
| 969 |
.BR openat (), |
| 970 |
and |
| 971 |
.BR creat () |
| 972 |
return the new file descriptor (a nonnegative integer). |
| 973 |
On error, \-1 is returned and |
| 974 |
.I errno |
| 975 |
is set to indicate the error. |
| 976 |
.SH ERRORS |
| 977 |
.BR open (), |
| 978 |
.BR openat (), |
| 979 |
and |
| 980 |
.BR creat () |
| 981 |
can fail with the following errors: |
| 982 |
.TP |
| 983 |
.B EACCES |
| 984 |
The requested access to the file is not allowed, or search permission |
| 985 |
is denied for one of the directories in the path prefix of |
| 986 |
.IR path , |
| 987 |
or the file did not exist yet and write access to the parent directory |
| 988 |
is not allowed. |
| 989 |
(See also |
| 990 |
.BR path_resolution (7).) |
| 991 |
.TP |
| 992 |
.B EACCES |
| 993 |
.\" commit 30aba6656f61ed44cba445a3c0d38b296fa9e8f5 |
| 994 |
Where |
| 995 |
.B O_CREAT |
| 996 |
is specified, the |
| 997 |
.I protected_fifos |
| 998 |
or |
| 999 |
.I protected_regular |
| 1000 |
sysctl is enabled, the file already exists and is a FIFO or regular file, the |
| 1001 |
owner of the file is neither the current user nor the owner of the |
| 1002 |
containing directory, and the containing directory is both world- or |
| 1003 |
group-writable and sticky. |
| 1004 |
For details, see the descriptions of |
| 1005 |
.I /proc/sys/fs/protected_fifos |
| 1006 |
and |
| 1007 |
.I /proc/sys/fs/protected_regular |
| 1008 |
in |
| 1009 |
.BR proc_sys_fs (5). |
| 1010 |
.TP |
| 1011 |
.B EBADF |
| 1012 |
.RB ( openat ()) |
| 1013 |
.I path |
| 1014 |
is relative but |
| 1015 |
.I dirfd |
| 1016 |
is neither |
| 1017 |
.B AT_FDCWD |
| 1018 |
nor a valid file descriptor. |
| 1019 |
.TP |
| 1020 |
.B EBUSY |
| 1021 |
.B O_EXCL |
| 1022 |
was specified in |
| 1023 |
.I flags |
| 1024 |
and |
| 1025 |
.I path |
| 1026 |
refers to a block device that is in use by the system (e.g., it is mounted). |
| 1027 |
.TP |
| 1028 |
.B EDQUOT |
| 1029 |
Where |
| 1030 |
.B O_CREAT |
| 1031 |
is specified, the file does not exist, and the user's quota of disk |
| 1032 |
blocks or inodes on the filesystem has been exhausted. |
| 1033 |
.TP |
| 1034 |
.B EEXIST |
| 1035 |
.I path |
| 1036 |
already exists and |
| 1037 |
.BR O_CREAT " and " O_EXCL |
| 1038 |
were used. |
| 1039 |
.TP |
| 1040 |
.B EFAULT |
| 1041 |
.I path |
| 1042 |
points outside your accessible address space. |
| 1043 |
.TP |
| 1044 |
.B EFBIG |
| 1045 |
See |
| 1046 |
.BR EOVERFLOW . |
| 1047 |
.TP |
| 1048 |
.B EINTR |
| 1049 |
While blocked waiting to complete an open of a slow device |
| 1050 |
(e.g., a FIFO; |
| 1051 |
see |
| 1052 |
.BR fifo (7)), |
| 1053 |
the call was interrupted by a signal handler; |
| 1054 |
see |
| 1055 |
.BR signal (7). |
| 1056 |
.TP |
| 1057 |
.B EINVAL |
| 1058 |
The filesystem does not support the |
| 1059 |
.B O_DIRECT |
| 1060 |
flag. |
| 1061 |
See |
| 1062 |
.B NOTES |
| 1063 |
for more information. |
| 1064 |
.TP |
| 1065 |
.B EINVAL |
| 1066 |
Invalid value in |
| 1067 |
.\" In particular, __O_TMPFILE instead of O_TMPFILE |
| 1068 |
.IR flags . |
| 1069 |
.TP |
| 1070 |
.B EINVAL |
| 1071 |
.B O_TMPFILE |
| 1072 |
was specified in |
| 1073 |
.IR flags , |
| 1074 |
but neither |
| 1075 |
.B O_WRONLY |
| 1076 |
nor |
| 1077 |
.B O_RDWR |
| 1078 |
was specified. |
| 1079 |
.TP |
| 1080 |
.B EINVAL |
| 1081 |
.B O_CREAT |
| 1082 |
and |
| 1083 |
.B O_DIRECTORY |
| 1084 |
were both specified in |
| 1085 |
.I flags , |
| 1086 |
and the Linux kernel version is 6.4 or later. |
| 1087 |
(Earlier kernels were inconsistent in this area, |
| 1088 |
and POSIX does not specify the behavior.) |
| 1089 |
.TP |
| 1090 |
.B EINVAL |
| 1091 |
.B O_CREAT |
| 1092 |
was specified in |
| 1093 |
.I flags |
| 1094 |
and the final component ("basename") of the new file's |
| 1095 |
.I path |
| 1096 |
is invalid |
| 1097 |
(e.g., it contains characters not permitted by the underlying filesystem). |
| 1098 |
.TP |
| 1099 |
.B EINVAL |
| 1100 |
The final component ("basename") of |
| 1101 |
.I path |
| 1102 |
is invalid |
| 1103 |
(e.g., it contains characters not permitted by the underlying filesystem). |
| 1104 |
.TP |
| 1105 |
.B EISDIR |
| 1106 |
.I path |
| 1107 |
refers to a directory and the access requested involved writing |
| 1108 |
(that is, |
| 1109 |
.B O_WRONLY |
| 1110 |
or |
| 1111 |
.B O_RDWR |
| 1112 |
is set). |
| 1113 |
.TP |
| 1114 |
.B EISDIR |
| 1115 |
.I path |
| 1116 |
refers to an existing directory, |
| 1117 |
.B O_TMPFILE |
| 1118 |
and one of |
| 1119 |
.B O_WRONLY |
| 1120 |
or |
| 1121 |
.B O_RDWR |
| 1122 |
were specified in |
| 1123 |
.IR flags , |
| 1124 |
but this kernel version does not provide the |
| 1125 |
.B O_TMPFILE |
| 1126 |
functionality. |
| 1127 |
.TP |
| 1128 |
.B ELOOP |
| 1129 |
Too many symbolic links were encountered in resolving |
| 1130 |
.IR path . |
| 1131 |
.TP |
| 1132 |
.B ELOOP |
| 1133 |
.I path |
| 1134 |
was a symbolic link, and |
| 1135 |
.I flags |
| 1136 |
specified |
| 1137 |
.B O_NOFOLLOW |
| 1138 |
but not |
| 1139 |
.BR O_PATH . |
| 1140 |
.TP |
| 1141 |
.B EMFILE |
| 1142 |
The per-process limit on the number of open file descriptors has been reached |
| 1143 |
(see the description of |
| 1144 |
.B RLIMIT_NOFILE |
| 1145 |
in |
| 1146 |
.BR getrlimit (2)). |
| 1147 |
.TP |
| 1148 |
.B ENAMETOOLONG |
| 1149 |
.I path |
| 1150 |
was too long. |
| 1151 |
.TP |
| 1152 |
.B ENFILE |
| 1153 |
The system-wide limit on the total number of open files has been reached. |
| 1154 |
.TP |
| 1155 |
.B ENODEV |
| 1156 |
.I path |
| 1157 |
refers to a device special file and no corresponding device exists. |
| 1158 |
(This is a Linux kernel bug; |
| 1159 |
in this situation |
| 1160 |
.B ENXIO |
| 1161 |
must be returned.) |
| 1162 |
.TP |
| 1163 |
.B ENOENT |
| 1164 |
.B O_CREAT |
| 1165 |
is not set and the named file does not exist. |
| 1166 |
.TP |
| 1167 |
.B ENOENT |
| 1168 |
A directory component in |
| 1169 |
.I path |
| 1170 |
does not exist or is a dangling symbolic link. |
| 1171 |
.TP |
| 1172 |
.B ENOENT |
| 1173 |
.I path |
| 1174 |
refers to a nonexistent directory, |
| 1175 |
.B O_TMPFILE |
| 1176 |
and one of |
| 1177 |
.B O_WRONLY |
| 1178 |
or |
| 1179 |
.B O_RDWR |
| 1180 |
were specified in |
| 1181 |
.IR flags , |
| 1182 |
but this kernel version does not provide the |
| 1183 |
.B O_TMPFILE |
| 1184 |
functionality. |
| 1185 |
.TP |
| 1186 |
.B ENOMEM |
| 1187 |
The named file is a FIFO, |
| 1188 |
but memory for the FIFO buffer can't be allocated because |
| 1189 |
the per-user hard limit on memory allocation for pipes has been reached |
| 1190 |
and the caller is not privileged; |
| 1191 |
see |
| 1192 |
.BR pipe (7). |
| 1193 |
.TP |
| 1194 |
.B ENOMEM |
| 1195 |
Insufficient kernel memory was available. |
| 1196 |
.TP |
| 1197 |
.B ENOSPC |
| 1198 |
.I path |
| 1199 |
was to be created but the device containing |
| 1200 |
.I path |
| 1201 |
has no room for the new file. |
| 1202 |
.TP |
| 1203 |
.B ENOTDIR |
| 1204 |
A component used as a directory in |
| 1205 |
.I path |
| 1206 |
is not, in fact, a directory, or |
| 1207 |
.B O_DIRECTORY |
| 1208 |
was specified and |
| 1209 |
.I path |
| 1210 |
was not a directory. |
| 1211 |
.TP |
| 1212 |
.B ENOTDIR |
| 1213 |
.RB ( openat ()) |
| 1214 |
.I path |
| 1215 |
is a relative pathname and |
| 1216 |
.I dirfd |
| 1217 |
is a file descriptor referring to a file other than a directory. |
| 1218 |
.TP |
| 1219 |
.B ENXIO |
| 1220 |
.BR O_NONBLOCK " | " O_WRONLY |
| 1221 |
is set, the named file is a FIFO, and |
| 1222 |
no process has the FIFO open for reading. |
| 1223 |
.TP |
| 1224 |
.B ENXIO |
| 1225 |
The file is a device special file and no corresponding device exists. |
| 1226 |
.TP |
| 1227 |
.B ENXIO |
| 1228 |
The file is a UNIX domain socket. |
| 1229 |
.TP |
| 1230 |
.B EOPNOTSUPP |
| 1231 |
The filesystem containing |
| 1232 |
.I path |
| 1233 |
does not support |
| 1234 |
.BR O_TMPFILE . |
| 1235 |
.TP |
| 1236 |
.B EOVERFLOW |
| 1237 |
.I path |
| 1238 |
refers to a regular file that is too large to be opened. |
| 1239 |
The usual scenario here is that an application compiled |
| 1240 |
on a 32-bit platform without |
| 1241 |
.I \-D_FILE_OFFSET_BITS=64 |
| 1242 |
tried to open a file whose size exceeds |
| 1243 |
.I (1<<31)\-1 |
| 1244 |
bytes; |
| 1245 |
see also |
| 1246 |
.B O_LARGEFILE |
| 1247 |
above. |
| 1248 |
This is the error specified by POSIX.1; |
| 1249 |
before Linux 2.6.24, Linux gave the error |
| 1250 |
.B EFBIG |
| 1251 |
for this case. |
| 1252 |
.\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253 |
| 1253 |
.\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW" |
| 1254 |
.\" Reported 2006-10-03 |
| 1255 |
.TP |
| 1256 |
.B EPERM |
| 1257 |
The |
| 1258 |
.B O_NOATIME |
| 1259 |
flag was specified, but the effective user ID of the caller |
| 1260 |
.\" Strictly speaking, it's the filesystem UID... (MTK) |
| 1261 |
did not match the owner of the file and the caller was not privileged. |
| 1262 |
.TP |
| 1263 |
.B EPERM |
| 1264 |
The operation was prevented by a file seal; |
| 1265 |
see |
| 1266 |
.BR fcntl (2). |
| 1267 |
.TP |
| 1268 |
.B EROFS |
| 1269 |
.I path |
| 1270 |
refers to a file on a read-only filesystem and write access was |
| 1271 |
requested. |
| 1272 |
.TP |
| 1273 |
.B ETXTBSY |
| 1274 |
.I path |
| 1275 |
refers to an executable image which is currently being executed and |
| 1276 |
write access was requested. |
| 1277 |
.TP |
| 1278 |
.B ETXTBSY |
| 1279 |
.I path |
| 1280 |
refers to a file that is currently in use as a swap file, and the |
| 1281 |
.B O_TRUNC |
| 1282 |
flag was specified. |
| 1283 |
.TP |
| 1284 |
.B ETXTBSY |
| 1285 |
.I path |
| 1286 |
refers to a file that is currently being read by the kernel (e.g., for |
| 1287 |
module/firmware loading), and write access was requested. |
| 1288 |
.TP |
| 1289 |
.B EWOULDBLOCK |
| 1290 |
The |
| 1291 |
.B O_NONBLOCK |
| 1292 |
flag was specified, and an incompatible lease was held on the file |
| 1293 |
(see |
| 1294 |
.BR fcntl (2)). |
| 1295 |
.SH VERSIONS |
| 1296 |
The (undefined) effect of |
| 1297 |
.B O_RDONLY | O_TRUNC |
| 1298 |
varies among implementations. |
| 1299 |
On many systems the file is actually truncated. |
| 1300 |
.\" Linux 2.0, 2.5: truncate |
| 1301 |
.\" Solaris 5.7, 5.8: truncate |
| 1302 |
.\" Irix 6.5: truncate |
| 1303 |
.\" Tru64 5.1B: truncate |
| 1304 |
.\" HP-UX 11.22: truncate |
| 1305 |
.\" FreeBSD 4.7: truncate |
| 1306 |
.SS Synchronized I/O |
| 1307 |
The POSIX.1-2008 "synchronized I/O" option |
| 1308 |
specifies different variants of synchronized I/O, |
| 1309 |
and specifies the |
| 1310 |
.BR open () |
| 1311 |
flags |
| 1312 |
.BR O_SYNC , |
| 1313 |
.BR O_DSYNC , |
| 1314 |
and |
| 1315 |
.B O_RSYNC |
| 1316 |
for controlling the behavior. |
| 1317 |
Regardless of whether an implementation supports this option, |
| 1318 |
it must at least support the use of |
| 1319 |
.B O_SYNC |
| 1320 |
for regular files. |
| 1321 |
.P |
| 1322 |
Linux implements |
| 1323 |
.B O_SYNC |
| 1324 |
and |
| 1325 |
.BR O_DSYNC , |
| 1326 |
but not |
| 1327 |
.BR O_RSYNC . |
| 1328 |
Somewhat incorrectly, glibc defines |
| 1329 |
.B O_RSYNC |
| 1330 |
to have the same value as |
| 1331 |
.BR O_SYNC . |
| 1332 |
.RB ( O_RSYNC |
| 1333 |
is defined in the Linux header file |
| 1334 |
.I <asm/fcntl.h> |
| 1335 |
on HP PA-RISC, but it is not used.) |
| 1336 |
.P |
| 1337 |
.B O_SYNC |
| 1338 |
provides synchronized I/O |
| 1339 |
.I file |
| 1340 |
integrity completion, |
| 1341 |
meaning write operations will flush data and all associated metadata |
| 1342 |
to the underlying hardware. |
| 1343 |
.B O_DSYNC |
| 1344 |
provides synchronized I/O |
| 1345 |
.I data |
| 1346 |
integrity completion, |
| 1347 |
meaning write operations will flush data |
| 1348 |
to the underlying hardware, |
| 1349 |
but will only flush metadata updates that are required |
| 1350 |
to allow a subsequent read operation to complete successfully. |
| 1351 |
Data integrity completion can reduce the number of disk operations |
| 1352 |
that are required for applications that don't need the guarantees |
| 1353 |
of file integrity completion. |
| 1354 |
.P |
| 1355 |
To understand the difference between the two types of completion, |
| 1356 |
consider two pieces of file metadata: |
| 1357 |
the file last modification timestamp |
| 1358 |
.RI ( st_mtime ) |
| 1359 |
and the file length. |
| 1360 |
All write operations will update the last file modification timestamp, |
| 1361 |
but only writes that add data to the end of the |
| 1362 |
file will change the file length. |
| 1363 |
The last modification timestamp is not needed to ensure that |
| 1364 |
a read completes successfully, but the file length is. |
| 1365 |
Thus, |
| 1366 |
.B O_DSYNC |
| 1367 |
would only guarantee to flush updates to the file length metadata |
| 1368 |
(whereas |
| 1369 |
.B O_SYNC |
| 1370 |
would also always flush the last modification timestamp metadata). |
| 1371 |
.P |
| 1372 |
Before Linux 2.6.33, Linux implemented only the |
| 1373 |
.B O_SYNC |
| 1374 |
flag for |
| 1375 |
.BR open (). |
| 1376 |
However, when that flag was specified, |
| 1377 |
most filesystems actually provided the equivalent of synchronized I/O |
| 1378 |
.I data |
| 1379 |
integrity completion (i.e., |
| 1380 |
.B O_SYNC |
| 1381 |
was actually implemented as the equivalent of |
| 1382 |
.BR O_DSYNC ). |
| 1383 |
.P |
| 1384 |
Since Linux 2.6.33, proper |
| 1385 |
.B O_SYNC |
| 1386 |
support is provided. |
| 1387 |
However, to ensure backward binary compatibility, |
| 1388 |
.B O_DSYNC |
| 1389 |
was defined with the same value as the historical |
| 1390 |
.BR O_SYNC , |
| 1391 |
and |
| 1392 |
.B O_SYNC |
| 1393 |
was defined as a new (two-bit) flag value that includes the |
| 1394 |
.B O_DSYNC |
| 1395 |
flag value. |
| 1396 |
This ensures that applications compiled against |
| 1397 |
new headers get at least |
| 1398 |
.B O_DSYNC |
| 1399 |
semantics before Linux 2.6.33. |
| 1400 |
.\" |
| 1401 |
.SS C library/kernel differences |
| 1402 |
Since glibc 2.26, |
| 1403 |
the glibc wrapper function for |
| 1404 |
.BR open () |
| 1405 |
employs the |
| 1406 |
.BR openat () |
| 1407 |
system call, rather than the kernel's |
| 1408 |
.BR open () |
| 1409 |
system call. |
| 1410 |
For certain architectures, this is also true before glibc 2.26. |
| 1411 |
.\" |
| 1412 |
.SS POSIX |
| 1413 |
POSIX.1-2024 specifies |
| 1414 |
.BR O_CLOFORK , |
| 1415 |
but Linux doesn't support it. |
| 1416 |
.SH STANDARDS |
| 1417 |
.TP |
| 1418 |
.BR open () |
| 1419 |
.TQ |
| 1420 |
.BR creat () |
| 1421 |
.TQ |
| 1422 |
.BR openat () |
| 1423 |
POSIX.1-2024. |
| 1424 |
.TP |
| 1425 |
.BR openat2 (2) |
| 1426 |
Linux. |
| 1427 |
.TP |
| 1428 |
.B O_DIRECT |
| 1429 |
.TQ |
| 1430 |
.B O_NOATIME |
| 1431 |
.TQ |
| 1432 |
.B O_PATH |
| 1433 |
.TQ |
| 1434 |
.B O_TMPFILE |
| 1435 |
Linux. |
| 1436 |
.SH HISTORY |
| 1437 |
.TP |
| 1438 |
.BR open () |
| 1439 |
.TQ |
| 1440 |
.BR creat () |
| 1441 |
SVr4, 4.3BSD, POSIX.1-2001. |
| 1442 |
.TP |
| 1443 |
.BR openat () |
| 1444 |
POSIX.1-2008. |
| 1445 |
Linux 2.6.16, |
| 1446 |
glibc 2.4. |
| 1447 |
.TP |
| 1448 |
.B O_CLOEXEC |
| 1449 |
.TQ |
| 1450 |
.B O_DIRECTORY |
| 1451 |
.TQ |
| 1452 |
.B O_NOFOLLOW |
| 1453 |
POSIX.1-2008. |
| 1454 |
.SH NOTES |
| 1455 |
Under Linux, the |
| 1456 |
.B O_NONBLOCK |
| 1457 |
flag is sometimes used in cases where one wants to open |
| 1458 |
but does not necessarily have the intention to read or write. |
| 1459 |
For example, |
| 1460 |
this may be used to open a device in order to get a file descriptor |
| 1461 |
for use with |
| 1462 |
.BR ioctl (2). |
| 1463 |
.P |
| 1464 |
Note that |
| 1465 |
.BR open () |
| 1466 |
can open device special files, but |
| 1467 |
.BR creat () |
| 1468 |
cannot create them; |
| 1469 |
use |
| 1470 |
.BR mknod (2) |
| 1471 |
instead. |
| 1472 |
.P |
| 1473 |
If the file is newly created, its |
| 1474 |
.IR st_atime , |
| 1475 |
.IR st_ctime , |
| 1476 |
.I st_mtime |
| 1477 |
fields |
| 1478 |
(respectively, time of last access, time of last status change, and |
| 1479 |
time of last modification; |
| 1480 |
see |
| 1481 |
.BR stat (2)) |
| 1482 |
are set |
| 1483 |
to the current time, and so are the |
| 1484 |
.I st_ctime |
| 1485 |
and |
| 1486 |
.I st_mtime |
| 1487 |
fields of the |
| 1488 |
parent directory. |
| 1489 |
Otherwise, if the file is modified because of the |
| 1490 |
.B O_TRUNC |
| 1491 |
flag, its |
| 1492 |
.I st_ctime |
| 1493 |
and |
| 1494 |
.I st_mtime |
| 1495 |
fields are set to the current time. |
| 1496 |
.P |
| 1497 |
The files in the |
| 1498 |
.IR /proc/ pid /fd |
| 1499 |
directory show the open file descriptors of the process with the PID |
| 1500 |
.IR pid . |
| 1501 |
The files in the |
| 1502 |
.IR /proc/ pid /fdinfo |
| 1503 |
directory show even more information about these file descriptors. |
| 1504 |
See |
| 1505 |
.BR proc (5) |
| 1506 |
for further details of both of these directories. |
| 1507 |
.P |
| 1508 |
The Linux header file |
| 1509 |
.B <asm/fcntl.h> |
| 1510 |
doesn't define |
| 1511 |
.BR O_ASYNC ; |
| 1512 |
the (BSD-derived) |
| 1513 |
.B FASYNC |
| 1514 |
synonym is defined instead. |
| 1515 |
.\" |
| 1516 |
.\" |
| 1517 |
.SS Open file descriptions |
| 1518 |
The term open file description is the one used by POSIX to refer to the |
| 1519 |
entries in the system-wide table of open files. |
| 1520 |
In other contexts, this object is |
| 1521 |
variously also called an "open file object", |
| 1522 |
a "file handle", an "open file table entry", |
| 1523 |
or\[em]in kernel-developer parlance\[em]a |
| 1524 |
.IR "struct file" . |
| 1525 |
.P |
| 1526 |
When a file descriptor is duplicated (using |
| 1527 |
.BR dup (2) |
| 1528 |
or similar), |
| 1529 |
the duplicate refers to the same open file description |
| 1530 |
as the original file descriptor, |
| 1531 |
and the two file descriptors consequently share |
| 1532 |
the file offset and file status flags. |
| 1533 |
Such sharing can also occur between processes: |
| 1534 |
a child process created via |
| 1535 |
.BR fork (2) |
| 1536 |
inherits duplicates of its parent's file descriptors, |
| 1537 |
and those duplicates refer to the same open file descriptions. |
| 1538 |
.P |
| 1539 |
Each |
| 1540 |
.BR open () |
| 1541 |
of a file creates a new open file description; |
| 1542 |
thus, there may be multiple open file descriptions |
| 1543 |
corresponding to a file inode. |
| 1544 |
.P |
| 1545 |
On Linux, one can use the |
| 1546 |
.BR kcmp (2) |
| 1547 |
.B KCMP_FILE |
| 1548 |
operation to test whether two file descriptors |
| 1549 |
(in the same process or in two different processes) |
| 1550 |
refer to the same open file description. |
| 1551 |
.\" |
| 1552 |
.SS NFS |
| 1553 |
There are many infelicities in the protocol underlying NFS, affecting |
| 1554 |
amongst others |
| 1555 |
.BR O_SYNC " and " O_NDELAY . |
| 1556 |
.P |
| 1557 |
On NFS filesystems with UID mapping enabled, |
| 1558 |
.BR open () |
| 1559 |
may |
| 1560 |
return a file descriptor but, for example, |
| 1561 |
.BR read (2) |
| 1562 |
requests are denied |
| 1563 |
with |
| 1564 |
.BR EACCES . |
| 1565 |
This is because the client performs |
| 1566 |
.BR open () |
| 1567 |
by checking the |
| 1568 |
permissions, but UID mapping is performed by the server upon |
| 1569 |
read and write requests. |
| 1570 |
.\" |
| 1571 |
.\" |
| 1572 |
.SS FIFOs |
| 1573 |
Opening the read or write end of a FIFO blocks until the other |
| 1574 |
end is also opened (by another process or thread). |
| 1575 |
See |
| 1576 |
.BR fifo (7) |
| 1577 |
for further details. |
| 1578 |
.\" |
| 1579 |
.\" |
| 1580 |
.SS File access mode |
| 1581 |
Unlike the other values that can be specified in |
| 1582 |
.IR flags , |
| 1583 |
the |
| 1584 |
.I "access mode" |
| 1585 |
values |
| 1586 |
.BR O_RDONLY ", " O_WRONLY ", and " O_RDWR |
| 1587 |
do not specify individual bits. |
| 1588 |
Rather, they define the low order two bits of |
| 1589 |
.IR flags , |
| 1590 |
and are defined respectively as 0, 1, and 2. |
| 1591 |
In other words, the combination |
| 1592 |
.B "O_RDONLY | O_WRONLY" |
| 1593 |
is a logical error, and certainly does not have the same meaning as |
| 1594 |
.BR O_RDWR . |
| 1595 |
.P |
| 1596 |
Linux reserves the special, nonstandard access mode 3 (binary 11) in |
| 1597 |
.I flags |
| 1598 |
to mean: |
| 1599 |
check for read and write permission on the file and return a file descriptor |
| 1600 |
that can't be used for reading or writing. |
| 1601 |
This nonstandard access mode is used by some Linux drivers to return a |
| 1602 |
file descriptor that is to be used only for device-specific |
| 1603 |
.BR ioctl (2) |
| 1604 |
operations. |
| 1605 |
.\" See for example util-linux's disk-utils/setfdprm.c |
| 1606 |
.\" For some background on access mode 3, see |
| 1607 |
.\" http://thread.gmane.org/gmane.linux.kernel/653123 |
| 1608 |
.\" "[RFC] correct flags to f_mode conversion in __dentry_open" |
| 1609 |
.\" LKML, 12 Mar 2008 |
| 1610 |
.\" |
| 1611 |
.\" |
| 1612 |
.SS Rationale for openat() and other "directory file descriptor" APIs |
| 1613 |
.BR openat () |
| 1614 |
and the other system calls and library functions that take |
| 1615 |
a directory file descriptor argument |
| 1616 |
(i.e., |
| 1617 |
.BR execveat (2), |
| 1618 |
.BR faccessat (2), |
| 1619 |
.BR fanotify_mark (2), |
| 1620 |
.BR fchmodat (2), |
| 1621 |
.BR fchownat (2), |
| 1622 |
.BR fspick (2), |
| 1623 |
.BR fstatat (2), |
| 1624 |
.BR futimesat (2), |
| 1625 |
.BR linkat (2), |
| 1626 |
.BR mkdirat (2), |
| 1627 |
.BR mknodat (2), |
| 1628 |
.BR mount_setattr (2), |
| 1629 |
.BR move_mount (2), |
| 1630 |
.BR name_to_handle_at (2), |
| 1631 |
.BR open_tree (2), |
| 1632 |
.BR openat2 (2), |
| 1633 |
.BR readlinkat (2), |
| 1634 |
.BR renameat (2), |
| 1635 |
.BR renameat2 (2), |
| 1636 |
.BR statx (2), |
| 1637 |
.BR symlinkat (2), |
| 1638 |
.BR unlinkat (2), |
| 1639 |
.BR utimensat (2), |
| 1640 |
.BR mkfifoat (3), |
| 1641 |
and |
| 1642 |
.BR scandirat (3)) |
| 1643 |
address two problems with the older interfaces that preceded them. |
| 1644 |
Here, the explanation is in terms of the |
| 1645 |
.BR openat () |
| 1646 |
call, but the rationale is analogous for the other interfaces. |
| 1647 |
.P |
| 1648 |
First, |
| 1649 |
.BR openat () |
| 1650 |
allows an application to avoid race conditions that could |
| 1651 |
occur when using |
| 1652 |
.BR open () |
| 1653 |
to open files in directories other than the current working directory. |
| 1654 |
These race conditions result from the fact that some component |
| 1655 |
of the directory prefix given to |
| 1656 |
.BR open () |
| 1657 |
could be changed in parallel with the call to |
| 1658 |
.BR open (). |
| 1659 |
Suppose, for example, that we wish to create the file |
| 1660 |
.I dir1/dir2/xxx.dep |
| 1661 |
if the file |
| 1662 |
.I dir1/dir2/xxx |
| 1663 |
exists. |
| 1664 |
The problem is that between the existence check and the file-creation step, |
| 1665 |
.I dir1 |
| 1666 |
or |
| 1667 |
.I dir2 |
| 1668 |
(which might be symbolic links) |
| 1669 |
could be modified to point to a different location. |
| 1670 |
Such races can be avoided by |
| 1671 |
opening a file descriptor for the target directory, |
| 1672 |
and then specifying that file descriptor as the |
| 1673 |
.I dirfd |
| 1674 |
argument of (say) |
| 1675 |
.BR fstatat (2) |
| 1676 |
and |
| 1677 |
.BR openat (). |
| 1678 |
The use of the |
| 1679 |
.I dirfd |
| 1680 |
file descriptor also has other benefits: |
| 1681 |
.IP \[bu] 3 |
| 1682 |
the file descriptor is a stable reference to the directory, |
| 1683 |
even if the directory is renamed; |
| 1684 |
and |
| 1685 |
.IP \[bu] |
| 1686 |
the open file descriptor prevents the underlying filesystem from |
| 1687 |
being dismounted, |
| 1688 |
just as when a process has a current working directory on a filesystem. |
| 1689 |
.P |
| 1690 |
Second, |
| 1691 |
.BR openat () |
| 1692 |
allows the implementation of a per-thread "current working |
| 1693 |
directory", via file descriptor(s) maintained by the application. |
| 1694 |
(This functionality can also be obtained by tricks based |
| 1695 |
on the use of |
| 1696 |
.IR /proc/self/fd/ dirfd, |
| 1697 |
but less efficiently.) |
| 1698 |
.P |
| 1699 |
The |
| 1700 |
.I dirfd |
| 1701 |
argument for these APIs can be obtained by using |
| 1702 |
.BR open () |
| 1703 |
or |
| 1704 |
.BR openat () |
| 1705 |
to open a directory (with either the |
| 1706 |
.B O_RDONLY |
| 1707 |
or the |
| 1708 |
.B O_PATH |
| 1709 |
flag). |
| 1710 |
Alternatively, such a file descriptor can be obtained by applying |
| 1711 |
.BR dirfd (3) |
| 1712 |
to a directory stream created using |
| 1713 |
.BR opendir (3). |
| 1714 |
.P |
| 1715 |
When these APIs are given a |
| 1716 |
.I dirfd |
| 1717 |
argument of |
| 1718 |
.B AT_FDCWD |
| 1719 |
or the specified pathname is absolute, |
| 1720 |
then they handle their pathname argument in the same way as |
| 1721 |
the corresponding conventional APIs. |
| 1722 |
However, in this case, several of the APIs have a |
| 1723 |
.I flags |
| 1724 |
argument that provides access to functionality that is not available with |
| 1725 |
the corresponding conventional APIs. |
| 1726 |
.\" |
| 1727 |
.\" |
| 1728 |
.SS O_DIRECT |
| 1729 |
The |
| 1730 |
.B O_DIRECT |
| 1731 |
flag may impose alignment restrictions on the length and address |
| 1732 |
of user-space buffers and the file offset of I/Os. |
| 1733 |
In Linux alignment |
| 1734 |
restrictions vary by filesystem and kernel version and might be |
| 1735 |
absent entirely. |
| 1736 |
The handling of misaligned |
| 1737 |
.B O_DIRECT |
| 1738 |
I/Os also varies; |
| 1739 |
they can either fail with |
| 1740 |
.B EINVAL |
| 1741 |
or fall back to buffered I/O. |
| 1742 |
.P |
| 1743 |
Since Linux 6.1, |
| 1744 |
.B O_DIRECT |
| 1745 |
support and alignment restrictions for a file can be queried using |
| 1746 |
.BR statx (2), |
| 1747 |
using the |
| 1748 |
.B STATX_DIOALIGN |
| 1749 |
flag. |
| 1750 |
Support for |
| 1751 |
.B STATX_DIOALIGN |
| 1752 |
varies by filesystem; |
| 1753 |
see |
| 1754 |
.BR statx (2). |
| 1755 |
.P |
| 1756 |
Some filesystems provide their own interfaces for querying |
| 1757 |
.B O_DIRECT |
| 1758 |
alignment restrictions, |
| 1759 |
for example the |
| 1760 |
.B XFS_IOC_DIOINFO |
| 1761 |
operation in |
| 1762 |
.BR xfsctl (3). |
| 1763 |
.B STATX_DIOALIGN |
| 1764 |
should be used instead when it is available. |
| 1765 |
.P |
| 1766 |
If none of the above is available, |
| 1767 |
then direct I/O support and alignment restrictions |
| 1768 |
can only be assumed from known characteristics of the filesystem, |
| 1769 |
the individual file, |
| 1770 |
the underlying storage device(s), |
| 1771 |
and the kernel version. |
| 1772 |
In Linux 2.4, |
| 1773 |
most filesystems based on block devices require that |
| 1774 |
the file offset and the length and memory address of all I/O segments |
| 1775 |
be multiples of the filesystem block size |
| 1776 |
(typically 4096 bytes). |
| 1777 |
In Linux 2.6.0, |
| 1778 |
this was relaxed to the logical block size of the block device |
| 1779 |
(typically 512 bytes). |
| 1780 |
A block device's logical block size can be determined using the |
| 1781 |
.BR ioctl (2) |
| 1782 |
.B BLKSSZGET |
| 1783 |
operation or from the shell using the command: |
| 1784 |
.P |
| 1785 |
.in +4n |
| 1786 |
.EX |
| 1787 |
blockdev \-\-getss |
| 1788 |
.EE |
| 1789 |
.in |
| 1790 |
.P |
| 1791 |
.B O_DIRECT |
| 1792 |
I/Os should never be run concurrently with the |
| 1793 |
.BR fork (2) |
| 1794 |
system call, |
| 1795 |
if the memory buffer is a private mapping |
| 1796 |
(i.e., any mapping created with the |
| 1797 |
.BR mmap (2) |
| 1798 |
.B MAP_PRIVATE |
| 1799 |
flag; |
| 1800 |
this includes memory allocated on the heap and statically allocated buffers). |
| 1801 |
Any such I/Os, whether submitted via an asynchronous I/O interface or from |
| 1802 |
another thread in the process, |
| 1803 |
should be completed before |
| 1804 |
.BR fork (2) |
| 1805 |
is called. |
| 1806 |
Failure to do so can result in data corruption and undefined behavior in |
| 1807 |
parent and child processes. |
| 1808 |
This restriction does not apply when the memory buffer for the |
| 1809 |
.B O_DIRECT |
| 1810 |
I/Os was created using |
| 1811 |
.BR shmat (2) |
| 1812 |
or |
| 1813 |
.BR mmap (2) |
| 1814 |
with the |
| 1815 |
.B MAP_SHARED |
| 1816 |
flag. |
| 1817 |
Nor does this restriction apply when the memory buffer has been advised as |
| 1818 |
.B MADV_DONTFORK |
| 1819 |
with |
| 1820 |
.BR madvise (2), |
| 1821 |
ensuring that it will not be available |
| 1822 |
to the child after |
| 1823 |
.BR fork (2). |
| 1824 |
.P |
| 1825 |
The |
| 1826 |
.B O_DIRECT |
| 1827 |
flag was introduced in SGI IRIX, where it has alignment |
| 1828 |
restrictions similar to those of Linux 2.4. |
| 1829 |
IRIX has also a |
| 1830 |
.BR fcntl (2) |
| 1831 |
call to query appropriate alignments, and sizes. |
| 1832 |
FreeBSD 4.x introduced |
| 1833 |
a flag of the same name, but without alignment restrictions. |
| 1834 |
.P |
| 1835 |
.B O_DIRECT |
| 1836 |
support was added in Linux 2.4.10. |
| 1837 |
Older Linux kernels simply ignore this flag. |
| 1838 |
Some filesystems may not implement the flag, in which case |
| 1839 |
.BR open () |
| 1840 |
fails with the error |
| 1841 |
.B EINVAL |
| 1842 |
if it is used. |
| 1843 |
.P |
| 1844 |
Applications should avoid mixing |
| 1845 |
.B O_DIRECT |
| 1846 |
and normal I/O to the same file, |
| 1847 |
and especially to overlapping byte regions in the same file. |
| 1848 |
Even when the filesystem correctly handles the coherency issues in |
| 1849 |
this situation, overall I/O throughput is likely to be slower than |
| 1850 |
using either mode alone. |
| 1851 |
Likewise, applications should avoid mixing |
| 1852 |
.BR mmap (2) |
| 1853 |
of files with direct I/O to the same files. |
| 1854 |
.P |
| 1855 |
The behavior of |
| 1856 |
.B O_DIRECT |
| 1857 |
with NFS will differ from local filesystems. |
| 1858 |
Older kernels, or |
| 1859 |
kernels configured in certain ways, may not support this combination. |
| 1860 |
The NFS protocol does not support passing the flag to the server, so |
| 1861 |
.B O_DIRECT |
| 1862 |
I/O will bypass the page cache only on the client; |
| 1863 |
the server may still |
| 1864 |
cache the I/O. |
| 1865 |
The client asks the server to make the I/O |
| 1866 |
synchronous to preserve the synchronous semantics of |
| 1867 |
.BR O_DIRECT . |
| 1868 |
Some servers will perform poorly under these circumstances, especially |
| 1869 |
if the I/O size is small. |
| 1870 |
Some servers may also be configured to |
| 1871 |
lie to clients about the I/O having reached stable storage; |
| 1872 |
this will avoid the performance penalty at some risk to data integrity |
| 1873 |
in the event of server power failure. |
| 1874 |
The Linux NFS client places no alignment restrictions on |
| 1875 |
.B O_DIRECT |
| 1876 |
I/O. |
| 1877 |
.P |
| 1878 |
In summary, |
| 1879 |
.B O_DIRECT |
| 1880 |
is a potentially powerful tool that should be used with caution. |
| 1881 |
It is recommended that applications treat use of |
| 1882 |
.B O_DIRECT |
| 1883 |
as a performance option which is disabled by default. |
| 1884 |
.SH BUGS |
| 1885 |
Currently, it is not possible to enable signal-driven |
| 1886 |
I/O by specifying |
| 1887 |
.B O_ASYNC |
| 1888 |
when calling |
| 1889 |
.BR open (); |
| 1890 |
use |
| 1891 |
.BR fcntl (2) |
| 1892 |
to enable this flag. |
| 1893 |
.\" FIXME . Check bugzilla report on open(O_ASYNC) |
| 1894 |
.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 |
| 1895 |
.P |
| 1896 |
One must check for two different error codes, |
| 1897 |
.B EISDIR |
| 1898 |
and |
| 1899 |
.BR ENOENT , |
| 1900 |
when trying to determine whether the kernel supports |
| 1901 |
.B O_TMPFILE |
| 1902 |
functionality. |
| 1903 |
.SH SEE ALSO |
| 1904 |
.BR chmod (2), |
| 1905 |
.BR chown (2), |
| 1906 |
.BR close (2), |
| 1907 |
.BR dup (2), |
| 1908 |
.BR fcntl (2), |
| 1909 |
.BR link (2), |
| 1910 |
.BR lseek (2), |
| 1911 |
.BR mknod (2), |
| 1912 |
.BR mmap (2), |
| 1913 |
.BR mount (2), |
| 1914 |
.BR open_by_handle_at (2), |
| 1915 |
.BR openat2 (2), |
| 1916 |
.BR read (2), |
| 1917 |
.BR socket (2), |
| 1918 |
.BR stat (2), |
| 1919 |
.BR umask (2), |
| 1920 |
.BR unlink (2), |
| 1921 |
.BR write (2), |
| 1922 |
.BR fopen (3), |
| 1923 |
.BR acl (5), |
| 1924 |
.BR fifo (7), |
| 1925 |
.BR inode (7), |
| 1926 |
.BR path_resolution (7), |
| 1927 |
.BR symlink (7) |