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 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
9 .\" Modified 1994-08-21 by Michael Haardt
10 .\" Modified 1996-04-13 by Andries Brouwer <aeb@cwi.nl>
11 .\" Modified 1996-05-13 by Thomas Koenig
12 .\" Modified 1996-12-20 by Michael Haardt
13 .\" Modified 1999-02-19 by Andries Brouwer <aeb@cwi.nl>
14 .\" Modified 1998-11-28 by Joseph S. Myers <jsm28@hermes.cam.ac.uk>
15 .\" Modified 1999-06-03 by Michael Haardt
16 .\" Modified 2002-05-07 by Michael Kerrisk <mtk.manpages@gmail.com>
17 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
18 .\" 2004-12-08, mtk, reordered flags list alphabetically
19 .\" 2004-12-08, Martin Pool <mbp@sourcefrog.net> (& mtk), added O_NOATIME
20 .\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits
21 .\" 2008-01-03, mtk, with input from Trond Myklebust
22 .\" <trond.myklebust@fys.uio.no> and Timo Sirainen <tss@iki.fi>
23 .\" Rewrite description of O_EXCL.
24 .\" 2008-01-11, Greg Banks <gnb@melbourne.sgi.com>: add more detail
26 .\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode
28 .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and
29 .\" O_TTYINIT. Eventually these may need to be documented. --mtk
31 .TH open 2 (date) "Linux man-pages (unreleased)"
33 open, openat, creat \- open and possibly create a file
36 .RI ( libc ", " \-lc )
41 .BI "int open(const char *" pathname ", int " flags ", ..."
42 .BI " \fR/*\fP mode_t " mode " \fR*/\fP );"
44 .BI "int creat(const char *" pathname ", mode_t " mode );
46 .BI "int openat(int " dirfd ", const char *" pathname ", int " flags ", ..."
47 .BI " \fR/*\fP mode_t " mode " \fR*/\fP );"
49 /* Documented separately, in \fBopenat2\fP(2): */
50 .BI "int openat2(int " dirfd ", const char *" pathname ,
51 .BI " const struct open_how *" how ", size_t " size );
55 Feature Test Macro Requirements for glibc (see
56 .BR feature_test_macros (7)):
62 _POSIX_C_SOURCE >= 200809L
69 system call opens the file specified by
71 If the specified file does not exist,
81 is a file descriptor, a small, nonnegative integer that is an index
82 to an entry in the process's table of open file descriptors.
83 The file descriptor is used
84 in subsequent system calls
91 to refer to the open file.
92 The file descriptor returned by a successful call will be
93 the lowest-numbered file descriptor not currently open for the process.
95 By default, the new file descriptor is set to remain open across an
99 file descriptor flag described in
101 is initially disabled); the
103 flag, described below, can be used to change this default.
104 The file offset is set to the beginning of the file (see
110 .IR "open file description" ,
111 an entry in the system-wide table of open files.
112 The open file description records the file offset and the file status flags
114 A file descriptor is a reference to an open file description;
115 this reference is unaffected if
117 is subsequently removed or modified to refer to a different file.
118 For further details on open file descriptions, see NOTES.
122 must include one of the following
124 .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR .
125 These request opening the file read-only, write-only, or read/write,
128 In addition, zero or more file creation flags and file status flags
134 .I file creation flags
147 are all of the remaining flags listed below.
148 .\" SUSv4 divides the flags into:
152 .\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
153 .\" though it's not clear what the difference between "other" and
154 .\" "File creation" flags is. I raised an Aardvark to see if this
155 .\" can be clarified in SUSv4; 10 Oct 2008.
156 .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67
157 .\" TC1 (balloted in 2013), resolved this, so that those three constants
158 .\" are also categorized" as file status flags.
160 The distinction between these two groups of flags is that
161 the file creation flags affect the semantics of the open operation itself,
162 while the file status flags affect the semantics of subsequent I/O operations.
163 The file status flags can be retrieved and (in some cases)
168 The full list of file creation flags and file status flags is as follows:
171 The file is opened in append mode.
174 the file offset is positioned at the end of the file,
177 The modification of the file offset and the write operation
178 are performed as a single atomic step.
181 may lead to corrupted files on NFS filesystems if more than one process
182 appends data to a file at once.
183 .\" For more background, see
184 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
185 .\" http://nfs.sourceforge.net/
186 This is because NFS does not support
187 appending to a file, so the client kernel has to simulate it, which
188 can't be done without a race condition.
191 Enable signal-driven I/O:
194 by default, but this can be changed via
196 when input or output becomes possible on this file descriptor.
197 This feature is available only for terminals, pseudoterminals,
198 sockets, and (since Linux 2.6) pipes and FIFOs.
202 See also BUGS, below.
204 .BR O_CLOEXEC " (since Linux 2.6.23)"
205 .\" NOTE! several other man pages refer to this text
206 Enable the close-on-exec flag for the new file descriptor.
207 .\" FIXME . for later review when Issue 8 is one day released...
208 .\" POSIX proposes to fix many APIs that provide hidden FDs
209 .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
210 .\" http://austingroupbugs.net/view.php?id=368
211 Specifying this flag permits a program to avoid additional
214 operations to set the
218 Note that the use of this flag is essential in some multithreaded programs,
219 because using a separate
224 flag does not suffice to avoid race conditions
225 where one thread opens a file descriptor and
226 attempts to set its close-on-exec flag using
228 at the same time as another thread does a
232 Depending on the order of execution,
233 the race may lead to the file descriptor returned by
235 being unintentionally leaked to the program executed by the child process
238 (This kind of race is in principle possible for any system call
239 that creates a file descriptor whose close-on-exec flag should be set,
240 and various other Linux system calls provide an equivalent of the
242 flag to deal with this problem.)
243 .\" This flag fixes only one form of the race condition;
244 .\" The race can also occur with, for example, file descriptors
245 .\" returned by accept(), pipe(), etc.
250 does not exist, create it as a regular file.
252 The owner (user ID) of the new file is set to the effective user ID
255 The group ownership (group ID) of the new file is set either to
256 the effective group ID of the process (System V semantics)
257 or to the group ID of the parent directory (BSD semantics).
258 On Linux, the behavior depends on whether the
259 set-group-ID mode bit is set on the parent directory:
260 if that bit is set, then BSD semantics apply;
261 otherwise, System V semantics apply.
262 For some filesystems, the behavior also depends on the
266 mount options described in
268 .\" As at Linux 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
269 .\" XFS (since Linux 2.6.14).
273 argument specifies the file mode bits to be applied when a new file is created.
282 is ignored (and can thus be specified as 0, or simply omitted).
293 if it is not supplied,
294 some arbitrary bytes from the stack will be applied as the file mode.
296 The effective mode is modified by the process's
298 in the usual way: in the absence of a default ACL, the mode of the
300 .IR "(mode\ &\ \[ti]umask)" .
304 applies only to future accesses of the
305 newly created file; the
307 call that creates a read-only file may well return a read/write
310 The following symbolic constants are provided for
315 00700 user (file owner) has read, write, and execute permission
318 00400 user has read permission
321 00200 user has write permission
324 00100 user has execute permission
327 00070 group has read, write, and execute permission
330 00040 group has read permission
333 00020 group has write permission
336 00010 group has execute permission
339 00007 others have read, write, and execute permission
342 00004 others have read permission
345 00002 others have write permission
348 00001 others have execute permission
351 According to POSIX, the effect when other bits are set in
354 On Linux, the following bits are also honored in
359 0004000 set-user-ID bit
362 0002000 set-group-ID bit (see
366 0001000 sticky bit (see
370 .BR O_DIRECT " (since Linux 2.4.10)"
371 Try to minimize cache effects of the I/O to and from this file.
372 In general this will degrade performance, but it is useful in
373 special situations, such as when applications do their own caching.
374 File I/O is done directly to/from user-space buffers.
377 flag on its own makes an effort to transfer data synchronously,
378 but does not give the guarantees of the
380 flag that data and necessary metadata are transferred.
381 To guarantee synchronous I/O,
383 must be used in addition to
385 See NOTES below for further discussion.
387 A semantically similar (but deprecated) interface for block devices
392 If \fIpathname\fP is not a directory, cause the open to fail.
393 .\" But see the following and its replies:
394 .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
395 .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
396 .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
397 This flag was added in Linux 2.1.126, to
398 avoid denial-of-service problems if
404 Write operations on the file will complete according to the requirements of
407 integrity completion.
412 return, the output data
413 has been transferred to the underlying hardware,
414 along with any file metadata that would be required to retrieve that data
415 (i.e., as though each
417 was followed by a call to
419 .IR "See NOTES below" .
422 Ensure that this call creates the file:
423 if this flag is specified in conjunction with
432 When these two flags are specified, symbolic links are not followed:
433 .\" POSIX.1-2001 explicitly requires this behavior.
436 is a symbolic link, then
438 fails regardless of where the symbolic link points.
440 In general, the behavior of
442 is undefined if it is used without
444 There is one exception: on Linux 2.6 and later,
450 refers to a block device.
451 If the block device is in use by the system (e.g., mounted),
458 is supported only when using NFSv3 or later on kernel 2.6 or later.
459 In NFS environments where
461 support is not provided, programs that rely on it
462 for performing locking tasks will contain a race condition.
463 Portable programs that want to perform atomic file locking using a lockfile,
464 and need to avoid reliance on NFS support for
466 can create a unique file on
467 the same filesystem (e.g., incorporating hostname and PID), and use
469 to make a link to the lockfile.
472 returns 0, the lock is successful.
475 on the unique file to check if its link count has increased to 2,
476 in which case the lock is also successful.
480 Allow files whose sizes cannot be represented in an
482 (but can be represented in an
486 .B _LARGEFILE64_SOURCE
487 macro must be defined
491 in order to obtain this definition.
494 feature test macro to 64 (rather than using
497 method of accessing large files on 32-bit systems (see
498 .BR feature_test_macros (7)).
500 .BR O_NOATIME " (since Linux 2.6.8)"
501 Do not update the file last access time
507 This flag can be employed only if one of the following conditions is true:
510 The effective UID of the process
511 .\" Strictly speaking: the filesystem UID
512 matches the owner UID of the file.
514 The calling process has the
516 capability in its user namespace and
517 the owner UID of the file has a mapping in the namespace.
520 This flag is intended for use by indexing or backup programs,
521 where its use can significantly reduce the amount of disk activity.
522 This flag may not be effective on all filesystems.
523 One example is NFS, where the server maintains the access time.
524 .\" The O_NOATIME flag also affects the treatment of st_atime
525 .\" by mmap() and readdir(2), MTK, Dec 04.
530 refers to a terminal device\[em]see
532 will not become the process's controlling terminal even if the
533 process does not have one.
536 If the trailing component (i.e., basename) of
538 is a symbolic link, then the open fails, with the error
540 Symbolic links in earlier components of the pathname will still be
544 error that can occur in this case is indistinguishable from the case where
545 an open fails because there are too many symbolic links found
546 while resolving components in the prefix part of the pathname.)
548 This flag is a FreeBSD extension, which was added in Linux 2.1.126,
549 and has subsequently been standardized in POSIX.1-2008.
554 .\" The headers from glibc 2.0.100 and later include a
555 .\" definition of this flag; \fIkernels before Linux 2.1.126 will ignore it if
558 .BR O_NONBLOCK " or " O_NDELAY
559 When possible, the file is opened in nonblocking mode.
562 nor any subsequent I/O operations on the file descriptor which is
563 returned will cause the calling process to wait.
565 Note that the setting of this flag has no effect on the operation of
570 since those interfaces merely inform the caller about whether
571 a file descriptor is "ready",
572 meaning that an I/O operation performed on
573 the file descriptor with the
579 Note that this flag has no effect for regular files and block devices;
580 that is, I/O operations will (briefly) block when device activity
581 is required, regardless of whether
586 semantics might eventually be implemented,
587 applications should not depend upon blocking behavior
588 when specifying this flag for regular files and block devices.
590 For the handling of FIFOs (named pipes), see also
592 For a discussion of the effect of
594 in conjunction with mandatory file locks and with file leases, see
597 .BR O_PATH " (since Linux 2.6.39)"
598 .\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd
599 .\" commit 326be7b484843988afe57566b627fb7a70beac56
600 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
602 .\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496
603 .\" Subject: Re: [PATCH] open(2): document O_PATH
604 .\" Newsgroups: gmane.linux.man, gmane.linux.kernel
606 Obtain a file descriptor that can be used for two purposes:
607 to indicate a location in the filesystem tree and
608 to perform operations that act purely at the file descriptor level.
609 The file itself is not opened, and other file operations (e.g.,
620 The following operations
622 be performed on the resulting file descriptor:
628 if the file descriptor refers to a directory
630 .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
635 .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
638 .\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf
640 Duplicating the file descriptor
646 Getting and setting file descriptor flags
652 Retrieving open file status flags using the
655 operation: the returned flags will include the bit
658 Passing the file descriptor as the
662 and the other "*at()" system calls.
668 .BR AT_SYMLINK_FOLLOW )
669 even if the file is not a directory.
671 Passing the file descriptor to another process via a UNIX domain socket
689 Opening a file or directory with the
691 flag requires no permissions on the object itself
692 (but does require execute permission on the directories in the path prefix).
693 Depending on the subsequent operation,
694 a check for suitable file permissions may be performed (e.g.,
696 requires execute permission on the directory referred to
697 by its file descriptor argument).
699 obtaining a reference to a filesystem object by opening it with the
701 flag requires that the caller have read permission on the object,
702 even when the subsequent operation (e.g.,
705 does not require read permission on the object.
709 is a symbolic link and the
711 flag is also specified,
712 then the call returns a file descriptor referring to the symbolic link.
713 This file descriptor can be used as the
721 with an empty pathname to have the calls operate on the symbolic link.
725 refers to an automount point that has not yet been triggered, so no
726 other filesystem is mounted on it, then the call returns a file
727 descriptor referring to the automount directory without triggering a mount.
729 can then be used to determine if it is, in fact, an untriggered
731 .RB ( ".f_type == AUTOFS_SUPER_MAGIC" ).
735 for regular files is to provide the equivalent of POSIX.1's
738 This permits us to open a file for which we have execute
739 permission but not read permission, and then execute that file,
740 with steps something like the following:
745 fd = open("some_prog", O_PATH);
746 snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd);
747 execl(buf, "some_prog", (char *) NULL);
753 file descriptor can also be passed as the argument of
757 Write operations on the file will complete according to the requirements of
761 (by contrast with the
771 returns, the output data and associated file metadata
772 have been transferred to the underlying hardware
773 (i.e., as though each
775 was followed by a call to
777 .IR "See NOTES below" .
779 .BR O_TMPFILE " (since Linux 3.11)"
780 .\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
781 .\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
782 .\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
783 Create an unnamed temporary regular file.
786 argument specifies a directory;
787 an unnamed inode will be created in that directory's filesystem.
788 Anything written to the resulting file will be lost when
789 the last file descriptor is closed, unless the file is given a name.
792 must be specified with one of
800 is not specified, then
802 can be used to link the temporary file into the filesystem, making it
803 permanent, using code like the following:
808 fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
811 /* File I/O on \[aq]fd\[aq]... */
813 linkat(fd, "", AT_FDCWD, "/path/for/file", AT_EMPTY_PATH);
815 /* If the caller doesn\[aq]t have the CAP_DAC_READ_SEARCH
816 capability (needed to use AT_EMPTY_PATH with linkat(2)),
817 and there is a proc(5) filesystem mounted, then the
818 linkat(2) call above can be replaced with:
820 snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd);
821 linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
831 argument determines the file permission mode, as with
838 prevents a temporary file from being linked into the filesystem
840 (Note that the meaning of
842 in this case is different from the meaning of
846 There are two main use cases for
847 .\" Inspired by http://lwn.net/Articles/559147/
853 functionality: race-free creation of temporary files that
854 (1) are automatically deleted when closed;
855 (2) can never be reached via any pathname;
856 (3) are not subject to symlink attacks; and
857 (4) do not require the caller to devise unique names.
859 Creating a file that is initially invisible, which is then populated
860 with data and adjusted to have appropriate filesystem attributes
865 before being atomically linked into the filesystem
866 in a fully formed state (using
872 requires support by the underlying filesystem;
873 only a subset of Linux filesystems provide that support.
874 In the initial implementation, support was provided in
875 the ext2, ext3, ext4, UDF, Minix, and tmpfs filesystems.
876 .\" To check for support, grep for "tmpfile" in kernel sources
877 Support for other filesystems has subsequently been added as follows:
879 .\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
880 .\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
882 .\" commit ef3b9af50bfa6a1f02cd7b3f5124b712b1ba3e3c
884 .\" commit 50732df02eefb39ab414ef655979c2c9b64ad21c
885 and ubifs (Linux 4.9)
888 If the file already exists and is a regular file and the access mode allows
893 it will be truncated to length 0.
894 If the file is a FIFO or terminal device file, the
897 Otherwise, the effect of
903 is equivalent to calling
908 .BR O_CREAT|O_WRONLY|O_TRUNC .
912 system call operates in exactly the same way as
914 except for the differences described here.
918 argument is used in conjunction with the
922 If the pathname given in
928 If the pathname given in
936 is interpreted relative to the current working
937 directory of the calling process (like
940 If the pathname given in
942 is relative, then it is interpreted relative to the directory
943 referred to by the file descriptor
945 (rather than relative to the current working directory of
946 the calling process, as is done by
948 for a relative pathname).
951 must be a directory that was opened for reading
957 If the pathname given in
961 is not a valid file descriptor, an error
964 (Specifying an invalid file descriptor number in
966 can be used as a means to ensure that
973 system call is an extension of
975 and provides a superset of the features of
977 It is documented separately, in
985 return the new file descriptor (a nonnegative integer).
986 On error, \-1 is returned and
988 is set to indicate the error.
994 can fail with the following errors:
997 The requested access to the file is not allowed, or search permission
998 is denied for one of the directories in the path prefix of
1000 or the file did not exist yet and write access to the parent directory
1003 .BR path_resolution (7).)
1006 .\" commit 30aba6656f61ed44cba445a3c0d38b296fa9e8f5
1012 .I protected_regular
1013 sysctl is enabled, the file already exists and is a FIFO or regular file, the
1014 owner of the file is neither the current user nor the owner of the
1015 containing directory, and the containing directory is both world- or
1016 group-writable and sticky.
1017 For details, see the descriptions of
1018 .I /proc/sys/fs/protected_fifos
1020 .I /proc/sys/fs/protected_regular
1031 nor a valid file descriptor.
1039 refers to a block device that is in use by the system (e.g., it is mounted).
1044 is specified, the file does not exist, and the user's quota of disk
1045 blocks or inodes on the filesystem has been exhausted.
1050 .BR O_CREAT " and " O_EXCL
1055 points outside your accessible address space.
1062 While blocked waiting to complete an open of a slow device
1065 the call was interrupted by a signal handler; see
1069 The filesystem does not support the
1074 for more information.
1078 .\" In particular, __O_TMPFILE instead of O_TMPFILE
1095 and the final component ("basename") of the new file's
1098 (e.g., it contains characters not permitted by the underlying filesystem).
1101 The final component ("basename") of
1104 (e.g., it contains characters not permitted by the underlying filesystem).
1108 refers to a directory and the access requested involved writing
1117 refers to an existing directory,
1125 but this kernel version does not provide the
1130 Too many symbolic links were encountered in resolving
1135 was a symbolic link, and
1143 The per-process limit on the number of open file descriptors has been reached
1144 (see the description of
1154 The system-wide limit on the total number of open files has been reached.
1158 refers to a device special file and no corresponding device exists.
1159 (This is a Linux kernel bug; in this situation
1165 is not set and the named file does not exist.
1168 A directory component in
1170 does not exist or is a dangling symbolic link.
1174 refers to a nonexistent directory,
1182 but this kernel version does not provide the
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; see
1194 Insufficient kernel memory was available.
1198 was to be created but the device containing
1200 has no room for the new file.
1203 A component used as a directory in
1205 is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and
1207 was not a directory.
1212 is a relative pathname and
1214 is a file descriptor referring to a file other than a directory.
1217 .BR O_NONBLOCK " | " O_WRONLY
1218 is set, the named file is a FIFO, and
1219 no process has the FIFO open for reading.
1222 The file is a device special file and no corresponding device exists.
1225 The file is a UNIX domain socket.
1228 The filesystem containing
1235 refers to a regular file that is too large to be opened.
1236 The usual scenario here is that an application compiled
1237 on a 32-bit platform without
1238 .I \-D_FILE_OFFSET_BITS=64
1239 tried to open a file whose size exceeds
1245 This is the error specified by POSIX.1;
1246 before Linux 2.6.24, Linux gave the error
1249 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253
1250 .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW"
1251 .\" Reported 2006-10-03
1256 flag was specified, but the effective user ID of the caller
1257 .\" Strictly speaking, it's the filesystem UID... (MTK)
1258 did not match the owner of the file and the caller was not privileged.
1261 The operation was prevented by a file seal; see
1266 refers to a file on a read-only filesystem and write access was
1271 refers to an executable image which is currently being executed and
1272 write access was requested.
1276 refers to a file that is currently in use as a swap file, and the
1282 refers to a file that is currently being read by the kernel (e.g., for
1283 module/firmware loading), and write access was requested.
1288 flag was specified, and an incompatible lease was held on the file
1292 The (undefined) effect of
1293 .B O_RDONLY | O_TRUNC
1294 varies among implementations.
1295 On many systems the file is actually truncated.
1296 .\" Linux 2.0, 2.5: truncate
1297 .\" Solaris 5.7, 5.8: truncate
1298 .\" Irix 6.5: truncate
1299 .\" Tru64 5.1B: truncate
1300 .\" HP-UX 11.22: truncate
1301 .\" FreeBSD 4.7: truncate
1302 .SS Synchronized I/O
1303 The POSIX.1-2008 "synchronized I/O" option
1304 specifies different variants of synchronized I/O,
1312 for controlling the behavior.
1313 Regardless of whether an implementation supports this option,
1314 it must at least support the use of
1324 Somewhat incorrectly, glibc defines
1326 to have the same value as
1329 is defined in the Linux header file
1331 on HP PA-RISC, but it is not used.)
1334 provides synchronized I/O
1336 integrity completion,
1337 meaning write operations will flush data and all associated metadata
1338 to the underlying hardware.
1340 provides synchronized I/O
1342 integrity completion,
1343 meaning write operations will flush data
1344 to the underlying hardware,
1345 but will only flush metadata updates that are required
1346 to allow a subsequent read operation to complete successfully.
1347 Data integrity completion can reduce the number of disk operations
1348 that are required for applications that don't need the guarantees
1349 of file integrity completion.
1351 To understand the difference between the two types of completion,
1352 consider two pieces of file metadata:
1353 the file last modification timestamp
1355 and the file length.
1356 All write operations will update the last file modification timestamp,
1357 but only writes that add data to the end of the
1358 file will change the file length.
1359 The last modification timestamp is not needed to ensure that
1360 a read completes successfully, but the file length is.
1363 would only guarantee to flush updates to the file length metadata
1366 would also always flush the last modification timestamp metadata).
1368 Before Linux 2.6.33, Linux implemented only the
1372 However, when that flag was specified,
1373 most filesystems actually provided the equivalent of synchronized I/O
1375 integrity completion (i.e.,
1377 was actually implemented as the equivalent of
1380 Since Linux 2.6.33, proper
1382 support is provided.
1383 However, to ensure backward binary compatibility,
1385 was defined with the same value as the historical
1389 was defined as a new (two-bit) flag value that includes the
1392 This ensures that applications compiled against
1393 new headers get at least
1395 semantics before Linux 2.6.33.
1397 .SS C library/kernel differences
1399 the glibc wrapper function for
1403 system call, rather than the kernel's
1406 For certain architectures, this is also true before glibc 2.26.
1426 flags are Linux-specific.
1429 to obtain their definitions.
1436 flags are not specified in POSIX.1-2001,
1437 but are specified in POSIX.1-2008.
1438 Since glibc 2.12, one can obtain their definitions by defining either
1440 with a value greater than or equal to 200809L or
1442 with a value greater than or equal to 700.
1443 In glibc 2.11 and earlier, one obtains the definitions by defining
1450 SVr4, 4.3BSD, POSIX.1-2001.
1459 flag is sometimes used in cases where one wants to open
1460 but does not necessarily have the intention to read or write.
1462 this may be used to open a device in order to get a file descriptor
1468 can open device special files, but
1470 cannot create them; use
1474 If the file is newly created, its
1479 (respectively, time of last access, time of last status change, and
1480 time of last modification; see
1483 to the current time, and so are the
1489 Otherwise, if the file is modified because of the
1495 fields are set to the current time.
1499 directory show the open file descriptors of the process with the PID
1502 .IR /proc/ pid /fdinfo
1503 directory show even more information about these file descriptors.
1506 for further details of both of these directories.
1508 The Linux header file
1514 synonym is defined instead.
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
1526 When a file descriptor is duplicated (using
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
1536 inherits duplicates of its parent's file descriptors,
1537 and those duplicates refer to the same open file descriptions.
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.
1545 On Linux, one can use the
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.
1553 There are many infelicities in the protocol underlying NFS, affecting
1555 .BR O_SYNC " and " O_NDELAY .
1557 On NFS filesystems with UID mapping enabled,
1560 return a file descriptor but, for example,
1565 This is because the client performs
1568 permissions, but UID mapping is performed by the server upon
1569 read and write requests.
1573 Opening the read or write end of a FIFO blocks until the other
1574 end is also opened (by another process or thread).
1577 for further details.
1580 .SS File access mode
1581 Unlike the other values that can be specified in
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
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
1596 Linux reserves the special, nonstandard access mode 3 (binary 11) in
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
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
1612 .SS Rationale for openat() and other "directory file descriptor" APIs
1614 and the other system calls and library functions that take
1615 a directory file descriptor argument
1619 .BR fanotify_mark (2),
1628 .BR mount_setattr (2),
1630 .BR name_to_handle_at (2),
1643 address two problems with the older interfaces that preceded them.
1644 Here, the explanation is in terms of the
1646 call, but the rationale is analogous for the other interfaces.
1650 allows an application to avoid race conditions that could
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
1657 could be changed in parallel with the call to
1659 Suppose, for example, that we wish to create the file
1660 .I dir1/dir2/xxx.dep
1664 The problem is that between the existence check and the file-creation step,
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
1680 file descriptor also has other benefits:
1682 the file descriptor is a stable reference to the directory,
1683 even if the directory is renamed; and
1685 the open file descriptor prevents the underlying filesystem from
1687 just as when a process has a current working directory on a filesystem.
1691 allows the implementation of a per-thread "current working
1692 directory", via file descriptor(s) maintained by the application.
1693 (This functionality can also be obtained by tricks based
1695 .IR /proc/self/fd/ dirfd,
1696 but less efficiently.)
1700 argument for these APIs can be obtained by using
1704 to open a directory (with either the
1709 Alternatively, such a file descriptor can be obtained by applying
1711 to a directory stream created using
1714 When these APIs are given a
1718 or the specified pathname is absolute,
1719 then they handle their pathname argument in the same way as
1720 the corresponding conventional APIs.
1721 However, in this case, several of the APIs have a
1723 argument that provides access to functionality that is not available with
1724 the corresponding conventional APIs.
1730 flag may impose alignment restrictions on the length and address
1731 of user-space buffers and the file offset of I/Os.
1733 restrictions vary by filesystem and kernel version and might be
1735 The handling of misaligned
1738 they can either fail with
1740 or fall back to buffered I/O.
1744 support and alignment restrictions for a file can be queried using
1751 varies by filesystem;
1755 Some filesystems provide their own interfaces for querying
1757 alignment restrictions,
1763 should be used instead when it is available.
1765 If none of the above is available,
1766 then direct I/O support and alignment restrictions
1767 can only be assumed from known characteristics of the filesystem,
1768 the individual file,
1769 the underlying storage device(s),
1770 and the kernel version.
1772 most filesystems based on block devices require that
1773 the file offset and the length and memory address of all I/O segments
1774 be multiples of the filesystem block size
1775 (typically 4096 bytes).
1777 this was relaxed to the logical block size of the block device
1778 (typically 512 bytes).
1779 A block device's logical block size can be determined using the
1782 operation or from the shell using the command:
1791 I/Os should never be run concurrently with the
1794 if the memory buffer is a private mapping
1795 (i.e., any mapping created with the
1799 this includes memory allocated on the heap and statically allocated buffers).
1800 Any such I/Os, whether submitted via an asynchronous I/O interface or from
1801 another thread in the process,
1802 should be completed before
1805 Failure to do so can result in data corruption and undefined behavior in
1806 parent and child processes.
1807 This restriction does not apply when the memory buffer for the
1809 I/Os was created using
1816 Nor does this restriction apply when the memory buffer has been advised as
1820 ensuring that it will not be available
1826 flag was introduced in SGI IRIX, where it has alignment
1827 restrictions similar to those of Linux 2.4.
1830 call to query appropriate alignments, and sizes.
1831 FreeBSD 4.x introduced
1832 a flag of the same name, but without alignment restrictions.
1835 support was added in Linux 2.4.10.
1836 Older Linux kernels simply ignore this flag.
1837 Some filesystems may not implement the flag, in which case
1839 fails with the error
1843 Applications should avoid mixing
1845 and normal I/O to the same file,
1846 and especially to overlapping byte regions in the same file.
1847 Even when the filesystem correctly handles the coherency issues in
1848 this situation, overall I/O throughput is likely to be slower than
1849 using either mode alone.
1850 Likewise, applications should avoid mixing
1852 of files with direct I/O to the same files.
1856 with NFS will differ from local filesystems.
1858 kernels configured in certain ways, may not support this combination.
1859 The NFS protocol does not support passing the flag to the server, so
1861 I/O will bypass the page cache only on the client; the server may
1862 still cache the I/O.
1863 The client asks the server to make the I/O
1864 synchronous to preserve the synchronous semantics of
1866 Some servers will perform poorly under these circumstances, especially
1867 if the I/O size is small.
1868 Some servers may also be configured to
1869 lie to clients about the I/O having reached stable storage; this
1870 will avoid the performance penalty at some risk to data integrity
1871 in the event of server power failure.
1872 The Linux NFS client places no alignment restrictions on
1878 is a potentially powerful tool that should be used with caution.
1879 It is recommended that applications treat use of
1881 as a performance option which is disabled by default.
1883 Currently, it is not possible to enable signal-driven
1890 to enable this flag.
1891 .\" FIXME . Check bugzilla report on open(O_ASYNC)
1892 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
1894 One must check for two different error codes,
1898 when trying to determine whether the kernel supports
1908 and the file specified by
1912 will create a regular file (i.e.,
1926 .BR open_by_handle_at (2),
1938 .BR path_resolution (7),
projects / thirdparty / man-pages.git / blob