1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
2 .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
3 .\" and Copyright (C) 2008 Greg Banks
4 .\" and Copyright (C) 2006, 2008, 2013, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
6 .\" %%%LICENSE_START(VERBATIM)
7 .\" Permission is granted to make and distribute verbatim copies of this
8 .\" manual provided the copyright notice and this permission notice are
9 .\" preserved on all copies.
11 .\" Permission is granted to copy and distribute modified versions of this
12 .\" manual under the conditions for verbatim copying, provided that the
13 .\" entire resulting derived work is distributed under the terms of a
14 .\" permission notice identical to this one.
16 .\" Since the Linux kernel and libraries are constantly changing, this
17 .\" manual page may be incorrect or out-of-date. The author(s) assume no
18 .\" responsibility for errors or omissions, or for damages resulting from
19 .\" the use of the information contained herein. The author(s) may not
20 .\" have taken the same level of care in the production of this manual,
21 .\" which is licensed free of charge, as they might when working
24 .\" Formatted or processed versions of this manual, if unaccompanied by
25 .\" the source, must acknowledge the copyright and authors of this work.
28 .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
29 .\" Modified 1994-08-21 by Michael Haardt
30 .\" Modified 1996-04-13 by Andries Brouwer <aeb@cwi.nl>
31 .\" Modified 1996-05-13 by Thomas Koenig
32 .\" Modified 1996-12-20 by Michael Haardt
33 .\" Modified 1999-02-19 by Andries Brouwer <aeb@cwi.nl>
34 .\" Modified 1998-11-28 by Joseph S. Myers <jsm28@hermes.cam.ac.uk>
35 .\" Modified 1999-06-03 by Michael Haardt
36 .\" Modified 2002-05-07 by Michael Kerrisk <mtk.manpages@gmail.com>
37 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
38 .\" 2004-12-08, mtk, reordered flags list alphabetically
39 .\" 2004-12-08, Martin Pool <mbp@sourcefrog.net> (& mtk), added O_NOATIME
40 .\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits
41 .\" 2008-01-03, mtk, with input from Trond Myklebust
42 .\" <trond.myklebust@fys.uio.no> and Timo Sirainen <tss@iki.fi>
43 .\" Rewrite description of O_EXCL.
44 .\" 2008-01-11, Greg Banks <gnb@melbourne.sgi.com>: add more detail
46 .\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode
48 .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and
49 .\" O_TTYINIT. Eventually these may need to be documented. --mtk
51 .TH OPEN 2 2017-05-03 "Linux" "Linux Programmer's Manual"
53 open, openat, creat \- open and possibly create a file
56 .B #include <sys/types.h>
57 .B #include <sys/stat.h>
60 .BI "int open(const char *" pathname ", int " flags );
61 .BI "int open(const char *" pathname ", int " flags ", mode_t " mode );
63 .BI "int creat(const char *" pathname ", mode_t " mode );
65 .BI "int openat(int " dirfd ", const char *" pathname ", int " flags );
66 .BI "int openat(int " dirfd ", const char *" pathname ", int " flags \
71 Feature Test Macro Requirements for glibc (see
72 .BR feature_test_macros (7)):
81 _POSIX_C_SOURCE\ >=\ 200809L
93 returns a file descriptor, a small, nonnegative integer
94 for use in subsequent system calls
95 .RB ( read "(2), " write "(2), " lseek "(2), " fcntl "(2), etc.)."
96 The file descriptor returned by a successful call will be
97 the lowest-numbered file descriptor not currently open for the process.
99 By default, the new file descriptor is set to remain open across an
103 file descriptor flag described in
105 is initially disabled); the
107 flag, described below, can be used to change this default.
108 The file offset is set to the beginning of the file (see
114 .IR "open file description" ,
115 an entry in the system-wide table of open files.
116 The open file description records the file offset and the file status flags
118 A file descriptor is a reference to an open file description;
119 this reference is unaffected if
121 is subsequently removed or modified to refer to a different file.
122 For further details on open file descriptions, see NOTES.
126 must include one of the following
128 .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR .
129 These request opening the file read-only, write-only, or read/write,
132 In addition, zero or more file creation flags and file status flags
138 .I file creation flags
151 are all of the remaining flags listed below.
152 .\" SUSv4 divides the flags into:
156 .\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
157 .\" though it's not clear what the difference between "other" and
158 .\" "File creation" flags is. I raised an Aardvark to see if this
159 .\" can be clarified in SUSv4; 10 Oct 2008.
160 .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67
161 .\" TC1 (balloted in 2013), resolved this, so that those three constants
162 .\" are also categorized" as file status flags.
164 The distinction between these two groups of flags is that
165 the file creation flags affect the semantics of the open operation itself,
166 while the file status flags affect the semantics of subsequent I/O operations.
167 The file status flags can be retrieved and (in some cases)
172 The full list of file creation flags and file status flags is as follows:
175 The file is opened in append mode.
178 the file offset is positioned at the end of the file,
181 The modification of the file offset and the write operation
182 are performed as a single atomic step.
185 may lead to corrupted files on NFS filesystems if more than one process
186 appends data to a file at once.
187 .\" For more background, see
188 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
189 .\" http://nfs.sourceforge.net/
190 This is because NFS does not support
191 appending to a file, so the client kernel has to simulate it, which
192 can't be done without a race condition.
195 Enable signal-driven I/O:
198 by default, but this can be changed via
200 when input or output becomes possible on this file descriptor.
201 This feature is available only for terminals, pseudoterminals,
202 sockets, and (since Linux 2.6) pipes and FIFOs.
206 See also BUGS, below.
208 .BR O_CLOEXEC " (since Linux 2.6.23)"
209 .\" NOTE! several other man pages refer to this text
210 Enable the close-on-exec flag for the new file descriptor.
211 .\" FIXME . for later review when Issue 8 is one day released...
212 .\" POSIX proposes to fix many APIs that provide hidden FDs
213 .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
214 .\" http://austingroupbugs.net/view.php?id=368
215 Specifying this flag permits a program to avoid additional
218 operations to set the
222 Note that the use of this flag is essential in some multithreaded programs,
223 because using a separate
228 flag does not suffice to avoid race conditions
229 where one thread opens a file descriptor and
230 attempts to set its close-on-exec flag using
232 at the same time as another thread does a
236 Depending on the order of execution,
237 the race may lead to the file descriptor returned by
239 being unintentionally leaked to the program executed by the child process
242 (This kind of race is in principle possible for any system call
243 that creates a file descriptor whose close-on-exec flag should be set,
244 and various other Linux system calls provide an equivalent of the
246 flag to deal with this problem.)
247 .\" This flag fixes only one form of the race condition;
248 .\" The race can also occur with, for example, file descriptors
249 .\" returned by accept(), pipe(), etc.
252 If the file does not exist, it will be created.
254 The owner (user ID) of the new file is set to the effective user ID
257 The group ownership (group ID) of the new file is set either to
258 the effective group ID of the process (System V semantics)
259 or to the group ID of the parent directory (BSD semantics).
260 On Linux, the behavior depends on whether the
261 set-group-ID mode bit is set on the parent directory:
262 if that bit is set, then BSD semantics apply;
263 otherwise, System V semantics apply.
264 For some filesystems, the behavior also depends on the
268 mount options described in
270 .\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
271 .\" XFS (since 2.6.14).
276 argument specifies the file mode bits be applied when a new file is created.
277 This argument must be supplied when
290 The effective mode is modified by the process's
292 in the usual way: in the absence of a default ACL, the mode of the
294 .IR "(mode\ &\ ~umask)" .
295 Note that this mode applies only to future accesses of the
296 newly created file; the
298 call that creates a read-only file may well return a read/write
301 The following symbolic constants are provided for
305 00700 user (file owner) has read, write, and execute permission
308 00400 user has read permission
311 00200 user has write permission
314 00100 user has execute permission
317 00070 group has read, write, and execute permission
320 00040 group has read permission
323 00020 group has write permission
326 00010 group has execute permission
329 00007 others have read, write, and execute permission
332 00004 others have read permission
335 00002 others have write permission
338 00001 others have execute permission
341 According to POSIX, the effect when other bits are set in
344 On Linux, the following bits are also honored in
349 0004000 set-user-ID bit
352 0002000 set-group-ID bit (see
356 0001000 sticky bit (see
360 .BR O_DIRECT " (since Linux 2.4.10)"
361 Try to minimize cache effects of the I/O to and from this file.
362 In general this will degrade performance, but it is useful in
363 special situations, such as when applications do their own caching.
364 File I/O is done directly to/from user-space buffers.
367 flag on its own makes an effort to transfer data synchronously,
368 but does not give the guarantees of the
370 flag that data and necessary metadata are transferred.
371 To guarantee synchronous I/O,
373 must be used in addition to
375 See NOTES below for further discussion.
377 A semantically similar (but deprecated) interface for block devices
382 If \fIpathname\fP is not a directory, cause the open to fail.
383 .\" But see the following and its replies:
384 .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
385 .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
386 .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
387 This flag was added in kernel version 2.1.126, to
388 avoid denial-of-service problems if
394 Write operations on the file will complete according to the requirements of
397 integrity completion.
402 return, the output data
403 has been transferred to the underlying hardware,
404 along with any file metadata that would be required to retrieve that data
405 (i.e., as though each
407 was followed by a call to
409 .IR "See NOTES below" .
412 Ensure that this call creates the file:
413 if this flag is specified in conjunction with
421 When these two flags are specified, symbolic links are not followed:
422 .\" POSIX.1-2001 explicitly requires this behavior.
425 is a symbolic link, then
427 fails regardless of where the symbolic link points to.
429 In general, the behavior of
431 is undefined if it is used without
433 There is one exception: on Linux 2.6 and later,
439 refers to a block device.
440 If the block device is in use by the system (e.g., mounted),
447 is supported only when using NFSv3 or later on kernel 2.6 or later.
448 In NFS environments where
450 support is not provided, programs that rely on it
451 for performing locking tasks will contain a race condition.
452 Portable programs that want to perform atomic file locking using a lockfile,
453 and need to avoid reliance on NFS support for
455 can create a unique file on
456 the same filesystem (e.g., incorporating hostname and PID), and use
458 to make a link to the lockfile.
461 returns 0, the lock is successful.
464 on the unique file to check if its link count has increased to 2,
465 in which case the lock is also successful.
469 Allow files whose sizes cannot be represented in an
471 (but can be represented in an
475 .B _LARGEFILE64_SOURCE
476 macro must be defined
480 in order to obtain this definition.
483 feature test macro to 64 (rather than using
486 method of accessing large files on 32-bit systems (see
487 .BR feature_test_macros (7)).
489 .BR O_NOATIME " (since Linux 2.6.8)"
490 Do not update the file last access time
496 This flag can be employed only if one of the following conditions is true:
499 The effective UID of the process
500 .\" Strictly speaking: the filesystem UID
501 matches the owner UID of the file.
503 The calling process has the
505 capability in its user namespace and
506 the owner UID of the file has a mapping in the namespace.
509 This flag is intended for use by indexing or backup programs,
510 where its use can significantly reduce the amount of disk activity.
511 This flag may not be effective on all filesystems.
512 One example is NFS, where the server maintains the access time.
513 .\" The O_NOATIME flag also affects the treatment of st_atime
514 .\" by mmap() and readdir(2), MTK, Dec 04.
519 refers to a terminal device\(emsee
521 will not become the process's controlling terminal even if the
522 process does not have one.
525 If \fIpathname\fP is a symbolic link, then the open fails, with the error
527 Symbolic links in earlier components of the pathname will still be
531 error that can occur in this case is indistinguishable from the case where
532 an open fails because there are too many symbolic links found
533 while resolving components in the prefix part of the pathname.)
535 This flag is a FreeBSD extension, which was added to Linux in version 2.1.126,
536 and has subsequently been standardized in POSIX.1-2008.
541 .\" The headers from glibc 2.0.100 and later include a
542 .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if
545 .BR O_NONBLOCK " or " O_NDELAY
546 When possible, the file is opened in nonblocking mode.
549 nor any subsequent operations on the file descriptor which is
550 returned will cause the calling process to wait.
552 Note that this flag has no effect for regular files and block devices;
553 that is, I/O operations will (briefly) block when device activity
554 is required, regardless of whether
559 semantics might eventually be implemented,
560 applications should not depend upon blocking behavior
561 when specifying this flag for regular files and block devices.
563 For the handling of FIFOs (named pipes), see also
565 For a discussion of the effect of
567 in conjunction with mandatory file locks and with file leases, see
570 .BR O_PATH " (since Linux 2.6.39)"
571 .\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd
572 .\" commit 326be7b484843988afe57566b627fb7a70beac56
573 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
575 .\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496
576 .\" Subject: Re: [PATCH] open(2): document O_PATH
577 .\" Newsgroups: gmane.linux.man, gmane.linux.kernel
579 Obtain a file descriptor that can be used for two purposes:
580 to indicate a location in the filesystem tree and
581 to perform operations that act purely at the file descriptor level.
582 The file itself is not opened, and other file operations (e.g.,
593 The following operations
595 be performed on the resulting file descriptor:
601 .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
604 .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
607 .\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf
609 Duplicating the file descriptor
615 Getting and setting file descriptor flags
621 Retrieving open file status flags using the
624 operation: the returned flags will include the bit
627 Passing the file descriptor as the
631 and the other "*at()" system calls.
637 .BR AT_SYMLINK_FOLLOW )
638 even if the file is not a directory.
640 Passing the file descriptor to another process via a UNIX domain socket
660 is a symbolic link and the
662 flag is also specified,
663 then the call returns a file descriptor referring to the symbolic link.
664 This file descriptor can be used as the
672 with an empty pathname to have the calls operate on the symbolic link.
676 refers to an automount point that has not yet been triggered, so no
677 other filesystem is mounted on it, then the call returns a file
678 descriptor referring to the automount directory without triggering a mount.
680 can then be used to determine if it is, in fact, an untriggered
682 .RB ( ".f_type == AUTOFS_SUPER_MAGIC" ).
685 Write operations on the file will complete according to the requirements of
689 (by contrast with the
699 return, the output data and associated file metadata
700 have been transferred to the underlying hardware
701 (i.e., as though each
703 was followed by a call to
705 .IR "See NOTES below" .
707 .BR O_TMPFILE " (since Linux 3.11)"
708 .\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
709 .\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
710 .\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
711 Create an unnamed temporary file.
714 argument specifies a directory;
715 an unnamed inode will be created in that directory's filesystem.
716 Anything written to the resulting file will be lost when
717 the last file descriptor is closed, unless the file is given a name.
720 must be specified with one of
728 is not specified, then
730 can be used to link the temporary file into the filesystem, making it
731 permanent, using code like the following:
736 fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
739 /* File I/O on 'fd'... */
741 snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd);
742 linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
751 argument determines the file permission mode, as with
758 prevents a temporary file from being linked into the filesystem
760 (Note that the meaning of
762 in this case is different from the meaning of
766 There are two main use cases for
767 .\" Inspired by http://lwn.net/Articles/559147/
773 functionality: race-free creation of temporary files that
774 (1) are automatically deleted when closed;
775 (2) can never be reached via any pathname;
776 (3) are not subject to symlink attacks; and
777 (4) do not require the caller to devise unique names.
779 Creating a file that is initially invisible, which is then populated
780 with data and adjusted to have appropriate filesystem attributes
785 before being atomically linked into the filesystem
786 in a fully formed state (using
792 requires support by the underlying filesystem;
793 only a subset of Linux filesystems provide that support.
794 In the initial implementation, support was provided in
795 the ext2, ext3, ext4, UDF, Minix, and shmem filesystems.
796 .\" To check for support, grep for "tmpfile" in kernel sources
797 Support for other filesystems has subsequently been added as follows:
799 .\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
800 .\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
802 .\" commit ef3b9af50bfa6a1f02cd7b3f5124b712b1ba3e3c
804 .\" commit 50732df02eefb39ab414ef655979c2c9b64ad21c
805 and ubifs (Linux 4.9)
808 If the file already exists and is a regular file and the access mode allows
813 it will be truncated to length 0.
814 If the file is a FIFO or terminal device file, the
817 Otherwise, the effect of
823 is equivalent to calling
828 .BR O_CREAT|O_WRONLY|O_TRUNC .
832 system call operates in exactly the same way as
834 except for the differences described here.
836 If the pathname given in
838 is relative, then it is interpreted relative to the directory
839 referred to by the file descriptor
841 (rather than relative to the current working directory of
842 the calling process, as is done by
844 for a relative pathname).
854 is interpreted relative to the current working
855 directory of the calling process (like
868 return the new file descriptor, or \-1 if an error occurred
871 is set appropriately).
877 can fail with the following errors:
880 The requested access to the file is not allowed, or search permission
881 is denied for one of the directories in the path prefix of
883 or the file did not exist yet and write access to the parent directory
886 .BR path_resolution (7).)
891 is specified, the file does not exist, and the user's quota of disk
892 blocks or inodes on the filesystem has been exhausted.
897 .BR O_CREAT " and " O_EXCL
902 points outside your accessible address space.
909 While blocked waiting to complete an open of a slow device
912 the call was interrupted by a signal handler; see
916 The filesystem does not support the
921 for more information.
925 .\" In particular, __O_TMPFILE instead of O_TMPFILE
940 refers to a directory and the access requested involved writing
949 refers to an existing directory,
957 but this kernel version does not provide the
962 Too many symbolic links were encountered in resolving
967 was a symbolic link, and
975 The per-process limit on the number of open file descriptors has been reached
976 (see the description of
986 The system-wide limit on the total number of open files has been reached.
990 refers to a device special file and no corresponding device exists.
991 (This is a Linux kernel bug; in this situation
997 is not set and the named file does not exist.
998 Or, a directory component in
1000 does not exist or is a dangling symbolic link.
1004 refers to a nonexistent directory,
1012 but this kernel version does not provide the
1017 The named file is a FIFO,
1018 but memory for the FIFO buffer can't be allocated because
1019 the per-user hard limit on memory allocation for pipes has been reached
1020 and the caller is not privileged; see
1024 Insufficient kernel memory was available.
1028 was to be created but the device containing
1030 has no room for the new file.
1033 A component used as a directory in
1035 is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and
1037 was not a directory.
1040 .BR O_NONBLOCK " | " O_WRONLY
1041 is set, the named file is a FIFO, and
1042 no process has the FIFO open for reading.
1045 The file is a device special file and no corresponding device exists.
1048 The filesystem containing
1055 refers to a regular file that is too large to be opened.
1056 The usual scenario here is that an application compiled
1057 on a 32-bit platform without
1058 .I -D_FILE_OFFSET_BITS=64
1059 tried to open a file whose size exceeds
1065 This is the error specified by POSIX.1;
1066 in kernels before 2.6.24, Linux gave the error
1069 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253
1070 .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW"
1071 .\" Reported 2006-10-03
1076 flag was specified, but the effective user ID of the caller
1077 .\" Strictly speaking, it's the filesystem UID... (MTK)
1078 did not match the owner of the file and the caller was not privileged.
1081 The operation was prevented by a file seal; see
1086 refers to a file on a read-only filesystem and write access was
1091 refers to an executable image which is currently being executed and
1092 write access was requested.
1097 flag was specified, and an incompatible lease was held on the file
1101 The following additional errors can occur for
1106 is not a valid file descriptor.
1110 is a relative pathname and
1112 is a file descriptor referring to a file other than a directory.
1115 was added to Linux in kernel 2.6.16;
1116 library support was added to glibc in version 2.4.
1120 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
1131 flags are Linux-specific.
1134 to obtain their definitions.
1141 flags are not specified in POSIX.1-2001,
1142 but are specified in POSIX.1-2008.
1143 Since glibc 2.12, one can obtain their definitions by defining either
1145 with a value greater than or equal to 200809L or
1147 with a value greater than or equal to 700.
1148 In glibc 2.11 and earlier, one obtains the definitions by defining
1152 .BR feature_test_macros (7),
1153 feature test macros such as
1154 .BR _POSIX_C_SOURCE ,
1158 must be defined before including
1164 flag indicates that one wants to open
1165 but does not necessarily have the intention to read or write.
1166 This is typically used to open devices in order to get a file descriptor
1170 The (undefined) effect of
1171 .B O_RDONLY | O_TRUNC
1172 varies among implementations.
1173 On many systems the file is actually truncated.
1174 .\" Linux 2.0, 2.5: truncate
1175 .\" Solaris 5.7, 5.8: truncate
1176 .\" Irix 6.5: truncate
1177 .\" Tru64 5.1B: truncate
1178 .\" HP-UX 11.22: truncate
1179 .\" FreeBSD 4.7: truncate
1183 can open device special files, but
1185 cannot create them; use
1189 If the file is newly created, its
1194 (respectively, time of last access, time of last status change, and
1195 time of last modification; see
1198 to the current time, and so are the
1204 Otherwise, if the file is modified because of the
1210 fields are set to the current time.
1214 directory show the open file descriptors of the process with the PID
1217 .I /proc/[pid]/fdinfo
1218 directory show even more information about these files descriptors.
1221 for further details of both of these directories.
1224 .SS Open file descriptions
1225 The term open file description is the one used by POSIX to refer to the
1226 entries in the system-wide table of open files.
1227 In other contexts, this object is
1228 variously also called an "open file object",
1229 a "file handle", an "open file table entry",
1230 or\(emin kernel-developer parlance\(ema
1233 When a file descriptor is duplicated (using
1236 the duplicate refers to the same open file description
1237 as the original file descriptor,
1238 and the two file descriptors consequently share
1239 the file offset and file status flags.
1240 Such sharing can also occur between processes:
1241 a child process created via
1243 inherits duplicates of its parent's file descriptors,
1244 and those duplicates refer to the same open file descriptions.
1248 of a file creates a new open file description;
1249 thus, there may be multiple open file descriptions
1250 corresponding to a file inode.
1252 On Linux, one can use the
1255 operation to test whether two file descriptors
1256 (in the same process or in two different processes)
1257 refer to the same open file description.
1260 .SS Synchronized I/O
1261 The POSIX.1-2008 "synchronized I/O" option
1262 specifies different variants of synchronized I/O,
1270 for controlling the behavior.
1271 Regardless of whether an implementation supports this option,
1272 it must at least support the use of
1282 (Somewhat incorrectly, glibc defines
1284 to have the same value as
1288 provides synchronized I/O
1290 integrity completion,
1291 meaning write operations will flush data and all associated metadata
1292 to the underlying hardware.
1294 provides synchronized I/O
1296 integrity completion,
1297 meaning write operations will flush data
1298 to the underlying hardware,
1299 but will only flush metadata updates that are required
1300 to allow a subsequent read operation to complete successfully.
1301 Data integrity completion can reduce the number of disk operations
1302 that are required for applications that don't need the guarantees
1303 of file integrity completion.
1305 To understand the difference between the two types of completion,
1306 consider two pieces of file metadata:
1307 the file last modification timestamp
1309 and the file length.
1310 All write operations will update the last file modification timestamp,
1311 but only writes that add data to the end of the
1312 file will change the file length.
1313 The last modification timestamp is not needed to ensure that
1314 a read completes successfully, but the file length is.
1317 would only guarantee to flush updates to the file length metadata
1320 would also always flush the last modification timestamp metadata).
1322 Before Linux 2.6.33, Linux implemented only the
1326 However, when that flag was specified,
1327 most filesystems actually provided the equivalent of synchronized I/O
1329 integrity completion (i.e.,
1331 was actually implemented as the equivalent of
1334 Since Linux 2.6.33, proper
1336 support is provided.
1337 However, to ensure backward binary compatibility,
1339 was defined with the same value as the historical
1343 was defined as a new (two-bit) flag value that includes the
1346 This ensures that applications compiled against
1347 new headers get at least
1349 semantics on pre-2.6.33 kernels.
1353 There are many infelicities in the protocol underlying NFS, affecting
1355 .BR O_SYNC " and " O_NDELAY .
1357 On NFS filesystems with UID mapping enabled,
1360 return a file descriptor but, for example,
1364 This is because the client performs
1367 permissions, but UID mapping is performed by the server upon
1368 read and write requests.
1372 Opening the read or write end of a FIFO blocks until the other
1373 end is also opened (by another process or thread).
1376 for further details.
1379 .SS File access mode
1380 Unlike the other values that can be specified in
1385 .BR O_RDONLY ", " O_WRONLY ", and " O_RDWR
1386 do not specify individual bits.
1387 Rather, they define the low order two bits of
1389 and are defined respectively as 0, 1, and 2.
1390 In other words, the combination
1391 .B "O_RDONLY | O_WRONLY"
1392 is a logical error, and certainly does not have the same meaning as
1395 Linux reserves the special, nonstandard access mode 3 (binary 11) in
1398 check for read and write permission on the file and return a file descriptor
1399 that can't be used for reading or writing.
1400 This nonstandard access mode is used by some Linux drivers to return a
1401 file descriptor that is to be used only for device-specific
1404 .\" See for example util-linux's disk-utils/setfdprm.c
1405 .\" For some background on access mode 3, see
1406 .\" http://thread.gmane.org/gmane.linux.kernel/653123
1407 .\" "[RFC] correct flags to f_mode conversion in __dentry_open"
1408 .\" LKML, 12 Mar 2008
1411 .SS Rationale for openat() and other "directory file descriptor" APIs
1413 and the other system calls and library functions that take
1414 a directory file descriptor argument
1418 .BR fanotify_mark (2),
1426 .BR name_to_handle_at (2),
1436 address two problems with the older interfaces that preceded them.
1437 Here, the explanation is in terms of the
1439 call, but the rationale is analogous for the other interfaces.
1443 allows an application to avoid race conditions that could
1446 to open files in directories other than the current working directory.
1447 These race conditions result from the fact that some component
1448 of the directory prefix given to
1450 could be changed in parallel with the call to
1452 Suppose, for example, that we wish to create the file
1457 The problem is that between the existence check and the file creation step,
1461 (which might be symbolic links)
1462 could be modified to point to a different location.
1463 Such races can be avoided by
1464 opening a file descriptor for the target directory,
1465 and then specifying that file descriptor as the
1473 file descriptor also has other benefits:
1475 the file descriptor is a stable reference to the directory,
1476 even if the directory is renamed; and
1478 the open file descriptor prevents the underlying filesystem from
1480 just as when a process has a current working directory on a filesystem.
1484 allows the implementation of a per-thread "current working
1485 directory", via file descriptor(s) maintained by the application.
1486 (This functionality can also be obtained by tricks based
1488 .IR /proc/self/fd/ dirfd,
1489 but less efficiently.)
1496 flag may impose alignment restrictions on the length and address
1497 of user-space buffers and the file offset of I/Os.
1499 restrictions vary by filesystem and kernel version and might be
1501 However there is currently no filesystem\-independent
1502 interface for an application to discover these restrictions for a given
1504 Some filesystems provide their own interfaces
1505 for doing so, for example the
1510 Under Linux 2.4, transfer sizes, and the alignment of the user buffer
1511 and the file offset must all be multiples of the logical block size
1513 Since Linux 2.6.0, alignment to the logical block size of the
1514 underlying storage (typically 512 bytes) suffices.
1515 The logical block size can be determined using the
1518 operation or from the shell using the command:
1523 I/Os should never be run concurrently with the
1526 if the memory buffer is a private mapping
1527 (i.e., any mapping created with the
1531 this includes memory allocated on the heap and statically allocated buffers).
1532 Any such I/Os, whether submitted via an asynchronous I/O interface or from
1533 another thread in the process,
1534 should be completed before
1537 Failure to do so can result in data corruption and undefined behavior in
1538 parent and child processes.
1539 This restriction does not apply when the memory buffer for the
1541 I/Os was created using
1548 Nor does this restriction apply when the memory buffer has been advised as
1552 ensuring that it will not be available
1558 flag was introduced in SGI IRIX, where it has alignment
1559 restrictions similar to those of Linux 2.4.
1562 call to query appropriate alignments, and sizes.
1563 FreeBSD 4.x introduced
1564 a flag of the same name, but without alignment restrictions.
1567 support was added under Linux in kernel version 2.4.10.
1568 Older Linux kernels simply ignore this flag.
1569 Some filesystems may not implement the flag and
1575 Applications should avoid mixing
1577 and normal I/O to the same file,
1578 and especially to overlapping byte regions in the same file.
1579 Even when the filesystem correctly handles the coherency issues in
1580 this situation, overall I/O throughput is likely to be slower than
1581 using either mode alone.
1582 Likewise, applications should avoid mixing
1584 of files with direct I/O to the same files.
1588 with NFS will differ from local filesystems.
1590 kernels configured in certain ways, may not support this combination.
1591 The NFS protocol does not support passing the flag to the server, so
1593 I/O will bypass the page cache only on the client; the server may
1594 still cache the I/O.
1595 The client asks the server to make the I/O
1596 synchronous to preserve the synchronous semantics of
1598 Some servers will perform poorly under these circumstances, especially
1599 if the I/O size is small.
1600 Some servers may also be configured to
1601 lie to clients about the I/O having reached stable storage; this
1602 will avoid the performance penalty at some risk to data integrity
1603 in the event of server power failure.
1604 The Linux NFS client places no alignment restrictions on
1610 is a potentially powerful tool that should be used with caution.
1611 It is recommended that applications treat use of
1613 as a performance option which is disabled by default.
1616 "The thing that has always disturbed me about O_DIRECT is that the whole
1617 interface is just stupid, and was probably designed by a deranged monkey
1618 on some serious mind-controlling substances."\(emLinus
1621 Currently, it is not possible to enable signal-driven
1628 to enable this flag.
1629 .\" FIXME . Check bugzilla report on open(O_ASYNC)
1630 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
1632 One must check for two different error codes,
1636 when trying to determine whether the kernel supports
1646 and the file specified by
1650 will create a regular file (i.e.,
1664 .BR open_by_handle_at (2),
1675 .BR path_resolution (7),