Debian Codegraph @

upstream/debian-unstable/man2/open.2

raw
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)