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-09-15 "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
91 system call opens the file specified by
93 If the specified file does not exist,
103 is a file descriptor, a small, nonnegative integer that is used
104 in subsequent system calls
105 .RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2),
106 etc.) to refer to the open file.
107 The file descriptor returned by a successful call will be
108 the lowest-numbered file descriptor not currently open for the process.
110 By default, the new file descriptor is set to remain open across an
114 file descriptor flag described in
116 is initially disabled); the
118 flag, described below, can be used to change this default.
119 The file offset is set to the beginning of the file (see
125 .IR "open file description" ,
126 an entry in the system-wide table of open files.
127 The open file description records the file offset and the file status flags
129 A file descriptor is a reference to an open file description;
130 this reference is unaffected if
132 is subsequently removed or modified to refer to a different file.
133 For further details on open file descriptions, see NOTES.
137 must include one of the following
139 .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR .
140 These request opening the file read-only, write-only, or read/write,
143 In addition, zero or more file creation flags and file status flags
149 .I file creation flags
162 are all of the remaining flags listed below.
163 .\" SUSv4 divides the flags into:
167 .\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
168 .\" though it's not clear what the difference between "other" and
169 .\" "File creation" flags is. I raised an Aardvark to see if this
170 .\" can be clarified in SUSv4; 10 Oct 2008.
171 .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67
172 .\" TC1 (balloted in 2013), resolved this, so that those three constants
173 .\" are also categorized" as file status flags.
175 The distinction between these two groups of flags is that
176 the file creation flags affect the semantics of the open operation itself,
177 while the file status flags affect the semantics of subsequent I/O operations.
178 The file status flags can be retrieved and (in some cases)
183 The full list of file creation flags and file status flags is as follows:
186 The file is opened in append mode.
189 the file offset is positioned at the end of the file,
192 The modification of the file offset and the write operation
193 are performed as a single atomic step.
196 may lead to corrupted files on NFS filesystems if more than one process
197 appends data to a file at once.
198 .\" For more background, see
199 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
200 .\" http://nfs.sourceforge.net/
201 This is because NFS does not support
202 appending to a file, so the client kernel has to simulate it, which
203 can't be done without a race condition.
206 Enable signal-driven I/O:
209 by default, but this can be changed via
211 when input or output becomes possible on this file descriptor.
212 This feature is available only for terminals, pseudoterminals,
213 sockets, and (since Linux 2.6) pipes and FIFOs.
217 See also BUGS, below.
219 .BR O_CLOEXEC " (since Linux 2.6.23)"
220 .\" NOTE! several other man pages refer to this text
221 Enable the close-on-exec flag for the new file descriptor.
222 .\" FIXME . for later review when Issue 8 is one day released...
223 .\" POSIX proposes to fix many APIs that provide hidden FDs
224 .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
225 .\" http://austingroupbugs.net/view.php?id=368
226 Specifying this flag permits a program to avoid additional
229 operations to set the
233 Note that the use of this flag is essential in some multithreaded programs,
234 because using a separate
239 flag does not suffice to avoid race conditions
240 where one thread opens a file descriptor and
241 attempts to set its close-on-exec flag using
243 at the same time as another thread does a
247 Depending on the order of execution,
248 the race may lead to the file descriptor returned by
250 being unintentionally leaked to the program executed by the child process
253 (This kind of race is in principle possible for any system call
254 that creates a file descriptor whose close-on-exec flag should be set,
255 and various other Linux system calls provide an equivalent of the
257 flag to deal with this problem.)
258 .\" This flag fixes only one form of the race condition;
259 .\" The race can also occur with, for example, file descriptors
260 .\" returned by accept(), pipe(), etc.
265 does not exist, create it as a regular file.
267 The owner (user ID) of the new file is set to the effective user ID
270 The group ownership (group ID) of the new file is set either to
271 the effective group ID of the process (System V semantics)
272 or to the group ID of the parent directory (BSD semantics).
273 On Linux, the behavior depends on whether the
274 set-group-ID mode bit is set on the parent directory:
275 if that bit is set, then BSD semantics apply;
276 otherwise, System V semantics apply.
277 For some filesystems, the behavior also depends on the
281 mount options described in
283 .\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
284 .\" XFS (since 2.6.14).
289 argument specifies the file mode bits be applied when a new file is created.
290 This argument must be supplied when
303 The effective mode is modified by the process's
305 in the usual way: in the absence of a default ACL, the mode of the
307 .IR "(mode\ &\ ~umask)" .
308 Note that this mode applies only to future accesses of the
309 newly created file; the
311 call that creates a read-only file may well return a read/write
314 The following symbolic constants are provided for
318 00700 user (file owner) has read, write, and execute permission
321 00400 user has read permission
324 00200 user has write permission
327 00100 user has execute permission
330 00070 group has read, write, and execute permission
333 00040 group has read permission
336 00020 group has write permission
339 00010 group has execute permission
342 00007 others have read, write, and execute permission
345 00004 others have read permission
348 00002 others have write permission
351 00001 others have execute permission
354 According to POSIX, the effect when other bits are set in
357 On Linux, the following bits are also honored in
362 0004000 set-user-ID bit
365 0002000 set-group-ID bit (see
369 0001000 sticky bit (see
373 .BR O_DIRECT " (since Linux 2.4.10)"
374 Try to minimize cache effects of the I/O to and from this file.
375 In general this will degrade performance, but it is useful in
376 special situations, such as when applications do their own caching.
377 File I/O is done directly to/from user-space buffers.
380 flag on its own makes an effort to transfer data synchronously,
381 but does not give the guarantees of the
383 flag that data and necessary metadata are transferred.
384 To guarantee synchronous I/O,
386 must be used in addition to
388 See NOTES below for further discussion.
390 A semantically similar (but deprecated) interface for block devices
395 If \fIpathname\fP is not a directory, cause the open to fail.
396 .\" But see the following and its replies:
397 .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
398 .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
399 .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
400 This flag was added in kernel version 2.1.126, to
401 avoid denial-of-service problems if
407 Write operations on the file will complete according to the requirements of
410 integrity completion.
415 return, the output data
416 has been transferred to the underlying hardware,
417 along with any file metadata that would be required to retrieve that data
418 (i.e., as though each
420 was followed by a call to
422 .IR "See NOTES below" .
425 Ensure that this call creates the file:
426 if this flag is specified in conjunction with
435 When these two flags are specified, symbolic links are not followed:
436 .\" POSIX.1-2001 explicitly requires this behavior.
439 is a symbolic link, then
441 fails regardless of where the symbolic link points.
443 In general, the behavior of
445 is undefined if it is used without
447 There is one exception: on Linux 2.6 and later,
453 refers to a block device.
454 If the block device is in use by the system (e.g., mounted),
461 is supported only when using NFSv3 or later on kernel 2.6 or later.
462 In NFS environments where
464 support is not provided, programs that rely on it
465 for performing locking tasks will contain a race condition.
466 Portable programs that want to perform atomic file locking using a lockfile,
467 and need to avoid reliance on NFS support for
469 can create a unique file on
470 the same filesystem (e.g., incorporating hostname and PID), and use
472 to make a link to the lockfile.
475 returns 0, the lock is successful.
478 on the unique file to check if its link count has increased to 2,
479 in which case the lock is also successful.
483 Allow files whose sizes cannot be represented in an
485 (but can be represented in an
489 .B _LARGEFILE64_SOURCE
490 macro must be defined
494 in order to obtain this definition.
497 feature test macro to 64 (rather than using
500 method of accessing large files on 32-bit systems (see
501 .BR feature_test_macros (7)).
503 .BR O_NOATIME " (since Linux 2.6.8)"
504 Do not update the file last access time
510 This flag can be employed only if one of the following conditions is true:
513 The effective UID of the process
514 .\" Strictly speaking: the filesystem UID
515 matches the owner UID of the file.
517 The calling process has the
519 capability in its user namespace and
520 the owner UID of the file has a mapping in the namespace.
523 This flag is intended for use by indexing or backup programs,
524 where its use can significantly reduce the amount of disk activity.
525 This flag may not be effective on all filesystems.
526 One example is NFS, where the server maintains the access time.
527 .\" The O_NOATIME flag also affects the treatment of st_atime
528 .\" by mmap() and readdir(2), MTK, Dec 04.
533 refers to a terminal device\(emsee
535 will not become the process's controlling terminal even if the
536 process does not have one.
539 If \fIpathname\fP is a symbolic link, then the open fails, with the error
541 Symbolic links in earlier components of the pathname will still be
545 error that can occur in this case is indistinguishable from the case where
546 an open fails because there are too many symbolic links found
547 while resolving components in the prefix part of the pathname.)
549 This flag is a FreeBSD extension, which was added to Linux in version 2.1.126,
550 and has subsequently been standardized in POSIX.1-2008.
555 .\" The headers from glibc 2.0.100 and later include a
556 .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if
559 .BR O_NONBLOCK " or " O_NDELAY
560 When possible, the file is opened in nonblocking mode.
563 nor any subsequent operations on the file descriptor which is
564 returned will cause the calling process to wait.
566 Note that this flag has no effect for regular files and block devices;
567 that is, I/O operations will (briefly) block when device activity
568 is required, regardless of whether
573 semantics might eventually be implemented,
574 applications should not depend upon blocking behavior
575 when specifying this flag for regular files and block devices.
577 For the handling of FIFOs (named pipes), see also
579 For a discussion of the effect of
581 in conjunction with mandatory file locks and with file leases, see
584 .BR O_PATH " (since Linux 2.6.39)"
585 .\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd
586 .\" commit 326be7b484843988afe57566b627fb7a70beac56
587 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
589 .\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496
590 .\" Subject: Re: [PATCH] open(2): document O_PATH
591 .\" Newsgroups: gmane.linux.man, gmane.linux.kernel
593 Obtain a file descriptor that can be used for two purposes:
594 to indicate a location in the filesystem tree and
595 to perform operations that act purely at the file descriptor level.
596 The file itself is not opened, and other file operations (e.g.,
607 The following operations
609 be performed on the resulting file descriptor:
615 if the file descriptor refers to a directory
617 .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
622 .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
625 .\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf
627 Duplicating the file descriptor
633 Getting and setting file descriptor flags
639 Retrieving open file status flags using the
642 operation: the returned flags will include the bit
645 Passing the file descriptor as the
649 and the other "*at()" system calls.
655 .BR AT_SYMLINK_FOLLOW )
656 even if the file is not a directory.
658 Passing the file descriptor to another process via a UNIX domain socket
676 Opening a file or directory with the
678 flag requires no permissions on the object itself
679 (but does require execute permission on the directories in the path prefix).
680 Depending on the subsequent operation,
681 a check for suitable file permissions may be performed (e.g.,
683 requires execute permission on the directory referred to
684 by its file descriptor argument).
686 obtaining a reference to a filesystem object by opening it with the
688 flag requires that the caller have read permission on the object,
689 even when the subsequent operation (e.g.,
692 does not require read permission on the object.
696 is a symbolic link and the
698 flag is also specified,
699 then the call returns a file descriptor referring to the symbolic link.
700 This file descriptor can be used as the
708 with an empty pathname to have the calls operate on the symbolic link.
712 refers to an automount point that has not yet been triggered, so no
713 other filesystem is mounted on it, then the call returns a file
714 descriptor referring to the automount directory without triggering a mount.
716 can then be used to determine if it is, in fact, an untriggered
718 .RB ( ".f_type == AUTOFS_SUPER_MAGIC" ).
722 for regular files is to provide the equivalent of POSIX.1's
725 This permits us to open a file for which we have execute
726 permission but not read permission, and then execute that file,
727 with steps something like the following:
732 fd = open("some_prog", O_PATH);
733 snprintf(buf, "/proc/self/fd/%d", fd);
734 execl(buf, "some_prog", (char *) NULL);
740 file descriptor can also be passed as the argument of
744 Write operations on the file will complete according to the requirements of
748 (by contrast with the
758 returns, the output data and associated file metadata
759 have been transferred to the underlying hardware
760 (i.e., as though each
762 was followed by a call to
764 .IR "See NOTES below" .
766 .BR O_TMPFILE " (since Linux 3.11)"
767 .\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
768 .\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
769 .\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
770 Create an unnamed temporary regular file.
773 argument specifies a directory;
774 an unnamed inode will be created in that directory's filesystem.
775 Anything written to the resulting file will be lost when
776 the last file descriptor is closed, unless the file is given a name.
779 must be specified with one of
787 is not specified, then
789 can be used to link the temporary file into the filesystem, making it
790 permanent, using code like the following:
795 fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
798 /* File I/O on 'fd'... */
800 snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd);
801 linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
810 argument determines the file permission mode, as with
817 prevents a temporary file from being linked into the filesystem
819 (Note that the meaning of
821 in this case is different from the meaning of
825 There are two main use cases for
826 .\" Inspired by http://lwn.net/Articles/559147/
832 functionality: race-free creation of temporary files that
833 (1) are automatically deleted when closed;
834 (2) can never be reached via any pathname;
835 (3) are not subject to symlink attacks; and
836 (4) do not require the caller to devise unique names.
838 Creating a file that is initially invisible, which is then populated
839 with data and adjusted to have appropriate filesystem attributes
844 before being atomically linked into the filesystem
845 in a fully formed state (using
851 requires support by the underlying filesystem;
852 only a subset of Linux filesystems provide that support.
853 In the initial implementation, support was provided in
854 the ext2, ext3, ext4, UDF, Minix, and shmem filesystems.
855 .\" To check for support, grep for "tmpfile" in kernel sources
856 Support for other filesystems has subsequently been added as follows:
858 .\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
859 .\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
861 .\" commit ef3b9af50bfa6a1f02cd7b3f5124b712b1ba3e3c
863 .\" commit 50732df02eefb39ab414ef655979c2c9b64ad21c
864 and ubifs (Linux 4.9)
867 If the file already exists and is a regular file and the access mode allows
872 it will be truncated to length 0.
873 If the file is a FIFO or terminal device file, the
876 Otherwise, the effect of
882 is equivalent to calling
887 .BR O_CREAT|O_WRONLY|O_TRUNC .
891 system call operates in exactly the same way as
893 except for the differences described here.
895 If the pathname given in
897 is relative, then it is interpreted relative to the directory
898 referred to by the file descriptor
900 (rather than relative to the current working directory of
901 the calling process, as is done by
903 for a relative pathname).
913 is interpreted relative to the current working
914 directory of the calling process (like
927 return the new file descriptor, or \-1 if an error occurred
930 is set appropriately).
936 can fail with the following errors:
939 The requested access to the file is not allowed, or search permission
940 is denied for one of the directories in the path prefix of
942 or the file did not exist yet and write access to the parent directory
945 .BR path_resolution (7).)
950 is specified, the file does not exist, and the user's quota of disk
951 blocks or inodes on the filesystem has been exhausted.
956 .BR O_CREAT " and " O_EXCL
961 points outside your accessible address space.
968 While blocked waiting to complete an open of a slow device
971 the call was interrupted by a signal handler; see
975 The filesystem does not support the
980 for more information.
984 .\" In particular, __O_TMPFILE instead of O_TMPFILE
1001 and the final component ("basename") of the new file's
1004 (e.g., it contains characters not permitted by the underlying filesystem).
1008 refers to a directory and the access requested involved writing
1017 refers to an existing directory,
1025 but this kernel version does not provide the
1030 Too many symbolic links were encountered in resolving
1035 was a symbolic link, and
1043 The per-process limit on the number of open file descriptors has been reached
1044 (see the description of
1054 The system-wide limit on the total number of open files has been reached.
1058 refers to a device special file and no corresponding device exists.
1059 (This is a Linux kernel bug; in this situation
1065 is not set and the named file does not exist.
1066 Or, a directory component in
1068 does not exist or is a dangling symbolic link.
1072 refers to a nonexistent directory,
1080 but this kernel version does not provide the
1085 The named file is a FIFO,
1086 but memory for the FIFO buffer can't be allocated because
1087 the per-user hard limit on memory allocation for pipes has been reached
1088 and the caller is not privileged; see
1092 Insufficient kernel memory was available.
1096 was to be created but the device containing
1098 has no room for the new file.
1101 A component used as a directory in
1103 is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and
1105 was not a directory.
1108 .BR O_NONBLOCK " | " O_WRONLY
1109 is set, the named file is a FIFO, and
1110 no process has the FIFO open for reading.
1113 The file is a device special file and no corresponding device exists.
1116 The filesystem containing
1123 refers to a regular file that is too large to be opened.
1124 The usual scenario here is that an application compiled
1125 on a 32-bit platform without
1126 .I -D_FILE_OFFSET_BITS=64
1127 tried to open a file whose size exceeds
1133 This is the error specified by POSIX.1;
1134 in kernels before 2.6.24, Linux gave the error
1137 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253
1138 .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW"
1139 .\" Reported 2006-10-03
1144 flag was specified, but the effective user ID of the caller
1145 .\" Strictly speaking, it's the filesystem UID... (MTK)
1146 did not match the owner of the file and the caller was not privileged.
1149 The operation was prevented by a file seal; see
1154 refers to a file on a read-only filesystem and write access was
1159 refers to an executable image which is currently being executed and
1160 write access was requested.
1164 refers to a file that is currently in use as a swap file, and the
1170 refers to a file that is currently being read by the kernel (e.g. for
1171 module/firmware loading), and write access was requested.
1176 flag was specified, and an incompatible lease was held on the file
1180 The following additional errors can occur for
1185 is not a valid file descriptor.
1189 is a relative pathname and
1191 is a file descriptor referring to a file other than a directory.
1194 was added to Linux in kernel 2.6.16;
1195 library support was added to glibc in version 2.4.
1199 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
1210 flags are Linux-specific.
1213 to obtain their definitions.
1220 flags are not specified in POSIX.1-2001,
1221 but are specified in POSIX.1-2008.
1222 Since glibc 2.12, one can obtain their definitions by defining either
1224 with a value greater than or equal to 200809L or
1226 with a value greater than or equal to 700.
1227 In glibc 2.11 and earlier, one obtains the definitions by defining
1231 .BR feature_test_macros (7),
1232 feature test macros such as
1233 .BR _POSIX_C_SOURCE ,
1237 must be defined before including
1243 flag indicates that one wants to open
1244 but does not necessarily have the intention to read or write.
1245 This is typically used to open devices in order to get a file descriptor
1249 The (undefined) effect of
1250 .B O_RDONLY | O_TRUNC
1251 varies among implementations.
1252 On many systems the file is actually truncated.
1253 .\" Linux 2.0, 2.5: truncate
1254 .\" Solaris 5.7, 5.8: truncate
1255 .\" Irix 6.5: truncate
1256 .\" Tru64 5.1B: truncate
1257 .\" HP-UX 11.22: truncate
1258 .\" FreeBSD 4.7: truncate
1262 can open device special files, but
1264 cannot create them; use
1268 If the file is newly created, its
1273 (respectively, time of last access, time of last status change, and
1274 time of last modification; see
1277 to the current time, and so are the
1283 Otherwise, if the file is modified because of the
1289 fields are set to the current time.
1293 directory show the open file descriptors of the process with the PID
1296 .I /proc/[pid]/fdinfo
1297 directory show even more information about these files descriptors.
1300 for further details of both of these directories.
1303 .SS Open file descriptions
1304 The term open file description is the one used by POSIX to refer to the
1305 entries in the system-wide table of open files.
1306 In other contexts, this object is
1307 variously also called an "open file object",
1308 a "file handle", an "open file table entry",
1309 or\(emin kernel-developer parlance\(ema
1312 When a file descriptor is duplicated (using
1315 the duplicate refers to the same open file description
1316 as the original file descriptor,
1317 and the two file descriptors consequently share
1318 the file offset and file status flags.
1319 Such sharing can also occur between processes:
1320 a child process created via
1322 inherits duplicates of its parent's file descriptors,
1323 and those duplicates refer to the same open file descriptions.
1327 of a file creates a new open file description;
1328 thus, there may be multiple open file descriptions
1329 corresponding to a file inode.
1331 On Linux, one can use the
1334 operation to test whether two file descriptors
1335 (in the same process or in two different processes)
1336 refer to the same open file description.
1339 .SS Synchronized I/O
1340 The POSIX.1-2008 "synchronized I/O" option
1341 specifies different variants of synchronized I/O,
1349 for controlling the behavior.
1350 Regardless of whether an implementation supports this option,
1351 it must at least support the use of
1361 (Somewhat incorrectly, glibc defines
1363 to have the same value as
1367 provides synchronized I/O
1369 integrity completion,
1370 meaning write operations will flush data and all associated metadata
1371 to the underlying hardware.
1373 provides synchronized I/O
1375 integrity completion,
1376 meaning write operations will flush data
1377 to the underlying hardware,
1378 but will only flush metadata updates that are required
1379 to allow a subsequent read operation to complete successfully.
1380 Data integrity completion can reduce the number of disk operations
1381 that are required for applications that don't need the guarantees
1382 of file integrity completion.
1384 To understand the difference between the two types of completion,
1385 consider two pieces of file metadata:
1386 the file last modification timestamp
1388 and the file length.
1389 All write operations will update the last file modification timestamp,
1390 but only writes that add data to the end of the
1391 file will change the file length.
1392 The last modification timestamp is not needed to ensure that
1393 a read completes successfully, but the file length is.
1396 would only guarantee to flush updates to the file length metadata
1399 would also always flush the last modification timestamp metadata).
1401 Before Linux 2.6.33, Linux implemented only the
1405 However, when that flag was specified,
1406 most filesystems actually provided the equivalent of synchronized I/O
1408 integrity completion (i.e.,
1410 was actually implemented as the equivalent of
1413 Since Linux 2.6.33, proper
1415 support is provided.
1416 However, to ensure backward binary compatibility,
1418 was defined with the same value as the historical
1422 was defined as a new (two-bit) flag value that includes the
1425 This ensures that applications compiled against
1426 new headers get at least
1428 semantics on pre-2.6.33 kernels.
1430 .SS C library/kernel differences
1432 the glibc wrapper function for
1436 system call, rather than the kernel's
1439 For certain architectures, this is also true in glibc versions before 2.26.
1442 There are many infelicities in the protocol underlying NFS, affecting
1444 .BR O_SYNC " and " O_NDELAY .
1446 On NFS filesystems with UID mapping enabled,
1449 return a file descriptor but, for example,
1453 This is because the client performs
1456 permissions, but UID mapping is performed by the server upon
1457 read and write requests.
1461 Opening the read or write end of a FIFO blocks until the other
1462 end is also opened (by another process or thread).
1465 for further details.
1468 .SS File access mode
1469 Unlike the other values that can be specified in
1474 .BR O_RDONLY ", " O_WRONLY ", and " O_RDWR
1475 do not specify individual bits.
1476 Rather, they define the low order two bits of
1478 and are defined respectively as 0, 1, and 2.
1479 In other words, the combination
1480 .B "O_RDONLY | O_WRONLY"
1481 is a logical error, and certainly does not have the same meaning as
1484 Linux reserves the special, nonstandard access mode 3 (binary 11) in
1487 check for read and write permission on the file and return a file descriptor
1488 that can't be used for reading or writing.
1489 This nonstandard access mode is used by some Linux drivers to return a
1490 file descriptor that is to be used only for device-specific
1493 .\" See for example util-linux's disk-utils/setfdprm.c
1494 .\" For some background on access mode 3, see
1495 .\" http://thread.gmane.org/gmane.linux.kernel/653123
1496 .\" "[RFC] correct flags to f_mode conversion in __dentry_open"
1497 .\" LKML, 12 Mar 2008
1500 .SS Rationale for openat() and other "directory file descriptor" APIs
1502 and the other system calls and library functions that take
1503 a directory file descriptor argument
1507 .BR fanotify_mark (2),
1515 .BR name_to_handle_at (2),
1525 address two problems with the older interfaces that preceded them.
1526 Here, the explanation is in terms of the
1528 call, but the rationale is analogous for the other interfaces.
1532 allows an application to avoid race conditions that could
1535 to open files in directories other than the current working directory.
1536 These race conditions result from the fact that some component
1537 of the directory prefix given to
1539 could be changed in parallel with the call to
1541 Suppose, for example, that we wish to create the file
1542 .I dir1/dir2/xxx.dep
1546 The problem is that between the existence check and the file-creation step,
1550 (which might be symbolic links)
1551 could be modified to point to a different location.
1552 Such races can be avoided by
1553 opening a file descriptor for the target directory,
1554 and then specifying that file descriptor as the
1562 file descriptor also has other benefits:
1564 the file descriptor is a stable reference to the directory,
1565 even if the directory is renamed; and
1567 the open file descriptor prevents the underlying filesystem from
1569 just as when a process has a current working directory on a filesystem.
1573 allows the implementation of a per-thread "current working
1574 directory", via file descriptor(s) maintained by the application.
1575 (This functionality can also be obtained by tricks based
1577 .IR /proc/self/fd/ dirfd,
1578 but less efficiently.)
1585 flag may impose alignment restrictions on the length and address
1586 of user-space buffers and the file offset of I/Os.
1588 restrictions vary by filesystem and kernel version and might be
1590 However there is currently no filesystem\-independent
1591 interface for an application to discover these restrictions for a given
1593 Some filesystems provide their own interfaces
1594 for doing so, for example the
1599 Under Linux 2.4, transfer sizes, and the alignment of the user buffer
1600 and the file offset must all be multiples of the logical block size
1602 Since Linux 2.6.0, alignment to the logical block size of the
1603 underlying storage (typically 512 bytes) suffices.
1604 The logical block size can be determined using the
1607 operation or from the shell using the command:
1614 I/Os should never be run concurrently with the
1617 if the memory buffer is a private mapping
1618 (i.e., any mapping created with the
1622 this includes memory allocated on the heap and statically allocated buffers).
1623 Any such I/Os, whether submitted via an asynchronous I/O interface or from
1624 another thread in the process,
1625 should be completed before
1628 Failure to do so can result in data corruption and undefined behavior in
1629 parent and child processes.
1630 This restriction does not apply when the memory buffer for the
1632 I/Os was created using
1639 Nor does this restriction apply when the memory buffer has been advised as
1643 ensuring that it will not be available
1649 flag was introduced in SGI IRIX, where it has alignment
1650 restrictions similar to those of Linux 2.4.
1653 call to query appropriate alignments, and sizes.
1654 FreeBSD 4.x introduced
1655 a flag of the same name, but without alignment restrictions.
1658 support was added under Linux in kernel version 2.4.10.
1659 Older Linux kernels simply ignore this flag.
1660 Some filesystems may not implement the flag, in which case
1662 fails with the error
1666 Applications should avoid mixing
1668 and normal I/O to the same file,
1669 and especially to overlapping byte regions in the same file.
1670 Even when the filesystem correctly handles the coherency issues in
1671 this situation, overall I/O throughput is likely to be slower than
1672 using either mode alone.
1673 Likewise, applications should avoid mixing
1675 of files with direct I/O to the same files.
1679 with NFS will differ from local filesystems.
1681 kernels configured in certain ways, may not support this combination.
1682 The NFS protocol does not support passing the flag to the server, so
1684 I/O will bypass the page cache only on the client; the server may
1685 still cache the I/O.
1686 The client asks the server to make the I/O
1687 synchronous to preserve the synchronous semantics of
1689 Some servers will perform poorly under these circumstances, especially
1690 if the I/O size is small.
1691 Some servers may also be configured to
1692 lie to clients about the I/O having reached stable storage; this
1693 will avoid the performance penalty at some risk to data integrity
1694 in the event of server power failure.
1695 The Linux NFS client places no alignment restrictions on
1701 is a potentially powerful tool that should be used with caution.
1702 It is recommended that applications treat use of
1704 as a performance option which is disabled by default.
1707 "The thing that has always disturbed me about O_DIRECT is that the whole
1708 interface is just stupid, and was probably designed by a deranged monkey
1709 on some serious mind-controlling substances."\(emLinus
1712 Currently, it is not possible to enable signal-driven
1719 to enable this flag.
1720 .\" FIXME . Check bugzilla report on open(O_ASYNC)
1721 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
1723 One must check for two different error codes,
1727 when trying to determine whether the kernel supports
1737 and the file specified by
1741 will create a regular file (i.e.,
1755 .BR open_by_handle_at (2),
1766 .BR path_resolution (7),
projects / thirdparty / man-pages.git / blob