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 2015-01-22 "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 _XOPEN_SOURCE\ >=\ 700 || _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
152 are all of the remaining flags listed below.
153 .\" SUSv4 divides the flags into:
157 .\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
158 .\" though it's not clear what the difference between "other" and
159 .\" "File creation" flags is. I raised an Aardvark to see if this
160 .\" can be clarified in SUSv4; 10 Oct 2008.
161 .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67
162 .\" TC1 (balloted in 2013), resolved this, so that those three constants
163 .\" are also categorized" as file status flags.
165 The distinction between these two groups of flags is that
166 the file status flags can be retrieved and (in some cases)
171 The full list of file creation flags and file status flags is as follows:
174 The file is opened in append mode.
177 the file offset is positioned at the end of the file,
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 Specifying this flag permits a program to avoid additional
210 operations to set the
214 Note that the use of this flag is essential in some multithreaded programs,
215 because using a separate
220 flag does not suffice to avoid race conditions
221 where one thread opens a file descriptor and
222 attempts to set its close-on-exec flag using
224 at the same time as another thread does a
228 Depending on the order of execution,
229 the race may lead to the file descriptor returned by
231 being unintentionally leaked to the program executed by the child process
234 (This kind of race is in principle possible for any system call
235 that creates a file descriptor whose close-on-exec flag should be set,
236 and various other Linux system calls provide an equivalent of the
238 flag to deal with this problem.)
239 .\" This flag fixes only one form of the race condition;
240 .\" The race can also occur with, for example, descriptors
241 .\" returned by accept(), pipe(), etc.
244 If the file does not exist, it will be created.
245 The owner (user ID) of the file is set to the effective user ID
247 The group ownership (group ID) is set either to
248 the effective group ID of the process or to the group ID of the
249 parent directory (depending on filesystem type and mount options,
250 and the mode of the parent directory; see the mount options
256 .\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
257 .\" XFS (since 2.6.14).
261 specifies the permissions to use in case a new file is created.
262 This argument must be supplied when
275 The effective permissions are modified by
278 in the usual way: The permissions of the created file are
279 .IR "(mode\ &\ ~umask)" .
280 Note that this mode applies only to future accesses of the
281 newly created file; the
283 call that creates a read-only file may well return a read/write
286 The following symbolic constants are provided for
290 00700 user (file owner) has read, write and execute permission
293 00400 user has read permission
296 00200 user has write permission
299 00100 user has execute permission
302 00070 group has read, write and execute permission
305 00040 group has read permission
308 00020 group has write permission
311 00010 group has execute permission
314 00007 others have read, write and execute permission
317 00004 others have read permission
320 00002 others have write permission
323 00001 others have execute permission
326 .BR O_DIRECT " (since Linux 2.4.10)"
327 Try to minimize cache effects of the I/O to and from this file.
328 In general this will degrade performance, but it is useful in
329 special situations, such as when applications do their own caching.
330 File I/O is done directly to/from user-space buffers.
333 flag on its own makes an effort to transfer data synchronously,
334 but does not give the guarantees of the
336 flag that data and necessary metadata are transferred.
337 To guarantee synchronous I/O,
339 must be used in addition to
341 See NOTES below for further discussion.
343 A semantically similar (but deprecated) interface for block devices
348 If \fIpathname\fP is not a directory, cause the open to fail.
349 .\" But see the following and its replies:
350 .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
351 .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
352 .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
353 This flag was added in kernel version 2.1.126, to
354 avoid denial-of-service problems if
360 Write operations on the file will complete according to the requirements of
363 integrity completion.
368 return, the output data
369 has been transferred to the underlying hardware,
370 along with any file metadata that would be required to retrieve that data
371 (i.e., as though each
373 was followed by a call to
375 .IR "See NOTES below" .
378 Ensure that this call creates the file:
379 if this flag is specified in conjunction with
387 When these two flags are specified, symbolic links are not followed:
388 .\" POSIX.1-2001 explicitly requires this behavior.
391 is a symbolic link, then
393 fails regardless of where the symbolic link points to.
395 In general, the behavior of
397 is undefined if it is used without
399 There is one exception: on Linux 2.6 and later,
405 refers to a block device.
406 If the block device is in use by the system (e.g., mounted),
413 is supported only when using NFSv3 or later on kernel 2.6 or later.
414 In NFS environments where
416 support is not provided, programs that rely on it
417 for performing locking tasks will contain a race condition.
418 Portable programs that want to perform atomic file locking using a lockfile,
419 and need to avoid reliance on NFS support for
421 can create a unique file on
422 the same filesystem (e.g., incorporating hostname and PID), and use
424 to make a link to the lockfile.
427 returns 0, the lock is successful.
430 on the unique file to check if its link count has increased to 2,
431 in which case the lock is also successful.
435 Allow files whose sizes cannot be represented in an
437 (but can be represented in an
441 .B _LARGEFILE64_SOURCE
442 macro must be defined
446 in order to obtain this definition.
449 feature test macro to 64 (rather than using
452 method of accessing large files on 32-bit systems (see
453 .BR feature_test_macros (7)).
455 .BR O_NOATIME " (since Linux 2.6.8)"
456 Do not update the file last access time
461 This flag is intended for use by indexing or backup programs,
462 where its use can significantly reduce the amount of disk activity.
463 This flag may not be effective on all filesystems.
464 One example is NFS, where the server maintains the access time.
465 .\" The O_NOATIME flag also affects the treatment of st_atime
466 .\" by mmap() and readdir(2), MTK, Dec 04.
471 refers to a terminal device\(emsee
473 will not become the process's controlling terminal even if the
474 process does not have one.
477 If \fIpathname\fP is a symbolic link, then the open fails.
478 This is a FreeBSD extension, which was added to Linux in version 2.1.126.
479 Symbolic links in earlier components of the pathname will still be
484 .\" The headers from glibc 2.0.100 and later include a
485 .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if
488 .BR O_NONBLOCK " or " O_NDELAY
489 When possible, the file is opened in nonblocking mode.
492 nor any subsequent operations on the file descriptor which is
493 returned will cause the calling process to wait.
494 For the handling of FIFOs (named pipes), see also
496 For a discussion of the effect of
498 in conjunction with mandatory file locks and with file leases, see
501 .BR O_PATH " (since Linux 2.6.39)"
502 .\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd
503 .\" commit 326be7b484843988afe57566b627fb7a70beac56
504 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
506 .\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496
507 .\" Subject: Re: [PATCH] open(2): document O_PATH
508 .\" Newsgroups: gmane.linux.man, gmane.linux.kernel
510 Obtain a file descriptor that can be used for two purposes:
511 to indicate a location in the filesystem tree and
512 to perform operations that act purely at the file descriptor level.
513 The file itself is not opened, and other file operations (e.g.,
523 The following operations
525 be performed on the resulting file descriptor:
531 .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
534 .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
536 Duplicating the file descriptor
542 Getting and setting file descriptor flags
548 Retrieving open file status flags using the
551 operation: the returned flags will include the bit
554 Passing the file descriptor as the
558 and the other "*at()" system calls.
564 .BR AT_SYMLINK_FOLLOW )
565 even if the file is not a directory.
567 Passing the file descriptor to another process via a UNIX domain socket
587 is a symbolic link and the
589 flag is also specified,
590 then the call returns a file descriptor referring to the symbolic link.
591 This file descriptor can be used as the
599 with an empty pathname to have the calls operate on the symbolic link.
602 Write operations on the file will complete according to the requirements of
606 (by contrast with the
616 return, the output data and associated file metadata
617 have been transferred to the underlying hardware
618 (i.e., as though each
620 was followed by a call to
622 .IR "See NOTES below" .
624 .BR O_TMPFILE " (since Linux 3.11)"
625 .\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
626 .\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
627 .\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
628 Create an unnamed temporary file.
631 argument specifies a directory;
632 an unnamed inode will be created in that directory's filesystem.
633 Anything written to the resulting file will be lost when
634 the last file descriptor is closed, unless the file is given a name.
637 must be specified with one of
645 is not specified, then
647 can be used to link the temporary file into the filesystem, making it
648 permanent, using code like the following:
653 fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
656 /* File I/O on 'fd'... */
658 snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd);
659 linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
668 argument determines the file permission mode, as with
675 prevents a temporary file from being linked into the filesystem
677 (Note that the meaning of
679 in this case is different from the meaning of
684 There are two main use cases for
685 .\" Inspired by http://lwn.net/Articles/559147/
691 functionality: race-free creation of temporary files that
692 (1) are automatically deleted when closed;
693 (2) can never be reached via any pathname;
694 (3) are not subject to symlink attacks; and
695 (4) do not require the caller to devise unique names.
697 Creating a file that is initially invisible, which is then populated
698 with data and adjusted to have appropriate filesystem attributes
703 before being atomically linked into the filesystem
704 in a fully formed state (using
710 requires support by the underlying filesystem;
711 only a subset of Linux filesystems provide that support.
712 In the initial implementation, support was provided in
713 the ext2, ext3, ext4, UDF, Minix, and shmem filesystems.
714 XFS support was added
715 .\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
716 .\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
720 If the file already exists and is a regular file and the access mode allows
725 it will be truncated to length 0.
726 If the file is a FIFO or terminal device file, the
729 Otherwise, the effect of
739 .BR O_CREAT|O_WRONLY|O_TRUNC .
743 system call operates in exactly the same way as
745 except for the differences described here.
747 If the pathname given in
749 is relative, then it is interpreted relative to the directory
750 referred to by the file descriptor
752 (rather than relative to the current working directory of
753 the calling process, as is done by
755 for a relative pathname).
765 is interpreted relative to the current working
766 directory of the calling process (like
779 return the new file descriptor, or \-1 if an error occurred
782 is set appropriately).
788 can fail with the following errors:
791 The requested access to the file is not allowed, or search permission
792 is denied for one of the directories in the path prefix of
794 or the file did not exist yet and write access to the parent directory
797 .BR path_resolution (7).)
802 is specified, the file does not exist, and the user's quota of disk
803 blocks or inodes on the filesystem has been exhausted.
808 .BR O_CREAT " and " O_EXCL
813 points outside your accessible address space.
820 While blocked waiting to complete an open of a slow device
823 the call was interrupted by a signal handler; see
827 The filesystem does not support the
832 for more information.
836 .\" In particular, __O_TMPFILE instead of O_TMPFILE
851 refers to a directory and the access requested involved writing
860 refers to an existing directory,
868 but this kernel version does not provide the
873 Too many symbolic links were encountered in resolving
878 was a symbolic link, and
886 The process already has the maximum number of files open
887 (see the description of
897 The system limit on the total number of open files has been reached.
901 refers to a device special file and no corresponding device exists.
902 (This is a Linux kernel bug; in this situation
908 is not set and the named file does not exist.
909 Or, a directory component in
911 does not exist or is a dangling symbolic link.
915 refers to a nonexistent directory,
923 but this kernel version does not provide the
928 Insufficient kernel memory was available.
932 was to be created but the device containing
934 has no room for the new file.
937 A component used as a directory in
939 is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and
944 .BR O_NONBLOCK " | " O_WRONLY
945 is set, the named file is a FIFO, and
946 no process has the FIFO open for reading.
947 Or, the file is a device special file and no corresponding device exists.
950 The filesystem containing
957 refers to a regular file that is too large to be opened.
958 The usual scenario here is that an application compiled
959 on a 32-bit platform without
960 .I -D_FILE_OFFSET_BITS=64
961 tried to open a file whose size exceeds
967 This is the error specified by POSIX.1-2001;
968 in kernels before 2.6.24, Linux gave the error
971 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253
972 .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW"
973 .\" Reported 2006-10-03
978 flag was specified, but the effective user ID of the caller
979 .\" Strictly speaking, it's the filesystem UID... (MTK)
980 did not match the owner of the file and the caller was not privileged
984 The operation was prevented by a file seal; see
989 refers to a file on a read-only filesystem and write access was
994 refers to an executable image which is currently being executed and
995 write access was requested.
1000 flag was specified, and an incompatible lease was held on the file
1004 The following additional errors can occur for
1009 is not a valid file descriptor.
1013 is a relative pathname and
1015 is a file descriptor referring to a file other than a directory.
1018 was added to Linux in kernel 2.6.16;
1019 library support was added to glibc in version 2.4.
1023 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
1034 flags are Linux-specific.
1037 to obtain their definitions.
1044 flags are not specified in POSIX.1-2001,
1045 but are specified in POSIX.1-2008.
1046 Since glibc 2.12, one can obtain their definitions by defining either
1048 with a value greater than or equal to 200809L or
1050 with a value greater than or equal to 700.
1051 In glibc 2.11 and earlier, one obtains the definitions by defining
1055 .BR feature_test_macros (7),
1056 feature test macros such as
1057 .BR _POSIX_C_SOURCE ,
1061 must be defined before including
1067 flag indicates that one wants to open
1068 but does not necessarily have the intention to read or write.
1069 This is typically used to open devices in order to get a file descriptor
1074 The (undefined) effect of
1075 .B O_RDONLY | O_TRUNC
1076 varies among implementations.
1077 On many systems the file is actually truncated.
1078 .\" Linux 2.0, 2.5: truncate
1079 .\" Solaris 5.7, 5.8: truncate
1080 .\" Irix 6.5: truncate
1081 .\" Tru64 5.1B: truncate
1082 .\" HP-UX 11.22: truncate
1083 .\" FreeBSD 4.7: truncate
1087 can open device special files, but
1089 cannot create them; use
1093 If the file is newly created, its
1098 (respectively, time of last access, time of last status change, and
1099 time of last modification; see
1102 to the current time, and so are the
1108 Otherwise, if the file is modified because of the
1110 flag, its st_ctime and st_mtime fields are set to the current time.
1113 .SS Open file descriptions
1114 The term open file description is the one used by POSIX to refer to the
1115 entries in the system-wide table of open files.
1116 In other contexts, this object is
1117 variously also called an "open file object",
1118 a "file handle", an "open file table entry",
1119 or\(emin kernel-developer parlance\(ema
1122 When a file descriptor is duplicated (using
1125 the duplicate refers to the same open file description
1126 as the original file descriptor,
1127 and the two file descriptors consequently share
1128 the file offset and file status flags.
1129 Such sharing can also occur between processes:
1130 a child process created via
1132 inherits duplicates of its parent's file descriptors,
1133 and those duplicates refer to the same open file descriptions.
1137 of a file creates a new open file description;
1138 thus, there may be multiple open file descriptions
1139 corresponding to a file inode.
1142 .SS Synchronized I/O
1143 The POSIX.1-2008 "synchronized I/O" option
1144 specifies different variants of synchronized I/O,
1152 for controlling the behavior.
1153 Regardless of whether an implementation supports this option,
1154 it must at least support the use of
1164 (Somewhat incorrectly, glibc defines
1166 to have the same value as
1170 provides synchronized I/O
1172 integrity completion,
1173 meaning write operations will flush data and all associated metadata
1174 to the underlying hardware.
1176 provides synchronized I/O
1178 integrity completion,
1179 meaning write operations will flush data
1180 to the underlying hardware,
1181 but will only flush metadata updates that are required
1182 to allow a subsequent read operation to complete successfully.
1183 Data integrity completion can reduce the number of disk operations
1184 that are required for applications that don't need the guarantees
1185 of file integrity completion.
1187 To understand the difference between the two types of completion,
1188 consider two pieces of file metadata:
1189 the file last modification timestamp
1191 and the file length.
1192 All write operations will update the last file modification timestamp,
1193 but only writes that add data to the end of the
1194 file will change the file length.
1195 The last modification timestamp is not needed to ensure that
1196 a read completes successfully, but the file length is.
1199 would only guarantee to flush updates to the file length metadata
1202 would also always flush the last modification timestamp metadata).
1204 Before Linux 2.6.33, Linux implemented only the
1208 However, when that flag was specified,
1209 most filesystems actually provided the equivalent of synchronized I/O
1211 integrity completion (i.e.,
1213 was actually implemented as the equivalent of
1216 Since Linux 2.6.33, proper
1218 support is provided.
1219 However, to ensure backward binary compatibility,
1221 was defined with the same value as the historical
1225 was defined as a new (two-bit) flag value that includes the
1228 This ensures that applications compiled against
1229 new headers get at least
1231 semantics on pre-2.6.33 kernels.
1235 There are many infelicities in the protocol underlying NFS, affecting
1237 .BR O_SYNC " and " O_NDELAY .
1239 On NFS filesystems with UID mapping enabled,
1242 return a file descriptor but, for example,
1246 This is because the client performs
1249 permissions, but UID mapping is performed by the server upon
1250 read and write requests.
1253 .SS File access mode
1254 Unlike the other values that can be specified in
1259 .BR O_RDONLY ", " O_WRONLY ", and " O_RDWR
1260 do not specify individual bits.
1261 Rather, they define the low order two bits of
1263 and are defined respectively as 0, 1, and 2.
1264 In other words, the combination
1265 .B "O_RDONLY | O_WRONLY"
1266 is a logical error, and certainly does not have the same meaning as
1269 Linux reserves the special, nonstandard access mode 3 (binary 11) in
1272 check for read and write permission on the file and return a descriptor
1273 that can't be used for reading or writing.
1274 This nonstandard access mode is used by some Linux drivers to return a
1275 descriptor that is to be used only for device-specific
1278 .\" See for example util-linux's disk-utils/setfdprm.c
1279 .\" For some background on access mode 3, see
1280 .\" http://thread.gmane.org/gmane.linux.kernel/653123
1281 .\" "[RFC] correct flags to f_mode conversion in __dentry_open"
1282 .\" LKML, 12 Mar 2008
1285 .SS Rationale for openat() and other "directory file descriptor" APIs
1287 and the other system calls and library functions that take
1288 a directory file descriptor argument
1292 .BR fanotify_mark (2),
1300 .BR name_to_handle_at (2),
1311 Here, the explanation is in terms of the
1313 call, but the rationale is analogous for the other interfaces.
1317 allows an application to avoid race conditions that could
1320 to open files in directories other than the current working directory.
1321 These race conditions result from the fact that some component
1322 of the directory prefix given to
1324 could be changed in parallel with the call to
1326 Suppose, for example, that we wish to create the file
1331 The problem is that between the existence check and the file creation step,
1335 (which might be symbolic links)
1336 could be modified to point to a different location.
1337 Such races can be avoided by
1338 opening a file descriptor for the target directory,
1339 and then specifying that file descriptor as the
1348 allows the implementation of a per-thread "current working
1349 directory", via file descriptor(s) maintained by the application.
1350 (This functionality can also be obtained by tricks based
1352 .IR /proc/self/fd/ dirfd,
1353 but less efficiently.)
1360 flag may impose alignment restrictions on the length and address
1361 of user-space buffers and the file offset of I/Os.
1363 restrictions vary by filesystem and kernel version and might be
1365 However there is currently no filesystem\-independent
1366 interface for an application to discover these restrictions for a given
1368 Some filesystems provide their own interfaces
1369 for doing so, for example the
1374 Under Linux 2.4, transfer sizes, and the alignment of the user buffer
1375 and the file offset must all be multiples of the logical block size
1377 Since Linux 2.6.0, alignment to the logical block size of the
1378 underlying storage (typically 512 bytes) suffices.
1379 The logical block size can be determined using the
1382 operation or from the shell using the command:
1387 I/Os should never be run concurrently with the
1390 if the memory buffer is a private mapping
1391 (i.e., any mapping created with the
1395 this includes memory allocated on the heap and statically allocated buffers).
1396 Any such I/Os, whether submitted via an asynchronous I/O interface or from
1397 another thread in the process,
1398 should be completed before
1401 Failure to do so can result in data corruption and undefined behavior in
1402 parent and child processes.
1403 This restriction does not apply when the memory buffer for the
1405 I/Os was created using
1412 Nor does this restriction apply when the memory buffer has been advised as
1416 ensuring that it will not be available
1422 flag was introduced in SGI IRIX, where it has alignment
1423 restrictions similar to those of Linux 2.4.
1426 call to query appropriate alignments, and sizes.
1427 FreeBSD 4.x introduced
1428 a flag of the same name, but without alignment restrictions.
1431 support was added under Linux in kernel version 2.4.10.
1432 Older Linux kernels simply ignore this flag.
1433 Some filesystems may not implement the flag and
1439 Applications should avoid mixing
1441 and normal I/O to the same file,
1442 and especially to overlapping byte regions in the same file.
1443 Even when the filesystem correctly handles the coherency issues in
1444 this situation, overall I/O throughput is likely to be slower than
1445 using either mode alone.
1446 Likewise, applications should avoid mixing
1448 of files with direct I/O to the same files.
1452 with NFS will differ from local filesystems.
1454 kernels configured in certain ways, may not support this combination.
1455 The NFS protocol does not support passing the flag to the server, so
1457 I/O will bypass the page cache only on the client; the server may
1458 still cache the I/O.
1459 The client asks the server to make the I/O
1460 synchronous to preserve the synchronous semantics of
1462 Some servers will perform poorly under these circumstances, especially
1463 if the I/O size is small.
1464 Some servers may also be configured to
1465 lie to clients about the I/O having reached stable storage; this
1466 will avoid the performance penalty at some risk to data integrity
1467 in the event of server power failure.
1468 The Linux NFS client places no alignment restrictions on
1474 is a potentially powerful tool that should be used with caution.
1475 It is recommended that applications treat use of
1477 as a performance option which is disabled by default.
1480 "The thing that has always disturbed me about O_DIRECT is that the whole
1481 interface is just stupid, and was probably designed by a deranged monkey
1482 on some serious mind-controlling substances."\(emLinus
1485 Currently, it is not possible to enable signal-driven
1492 to enable this flag.
1493 .\" FIXME . Check bugzilla report on open(O_ASYNC)
1494 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
1496 One must check for two different error codes,
1500 when trying to determine whether the kernel supports
1514 .BR open_by_handle_at (2),
1523 .BR path_resolution (7),
1526 This page is part of release 3.79 of the Linux
1529 A description of the project,
1530 information about reporting bugs,
1531 and the latest version of this page,
1533 \%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
