1OPEN(2) Linux Programmer's Manual OPEN(2)
2
6 open, openat, creat - open and possibly create a file
7
9 #include <sys/types.h>
10 #include <sys/stat.h>
11 #include <fcntl.h>
12 int open(const char *pathname, int flags);
14 int open(const char *pathname, int flags, mode_t mode);
15 int creat(const char *pathname, mode_t mode);
17 int openat(int dirfd, const char *pathname, int flags);
19 int openat(int dirfd, const char *pathname, int flags, mode_t mode);
20 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22 openat():
24 Since glibc 2.10:
25 _POSIX_C_SOURCE >= 200809L
26 Before glibc 2.10:
27 _ATFILE_SOURCE
28
30 The open() system call opens the file specified by pathname. If the
31 specified file does not exist, it may optionally (if O_CREAT is speci‐
32 fied in flags) be created by open().
33 The return value of open() is a file descriptor, a small, nonnegative
35 integer that is used in subsequent system calls (read(2), write(2),
36 lseek(2), fcntl(2), etc.) to refer to the open file. The file descrip‐
37 tor returned by a successful call will be the lowest-numbered file
38 descriptor not currently open for the process.
39 By default, the new file descriptor is set to remain open across an
41 execve(2) (i.e., the FD_CLOEXEC file descriptor flag described in
42 fcntl(2) is initially disabled); the O_CLOEXEC flag, described below,
43 can be used to change this default. The file offset is set to the
44 beginning of the file (see lseek(2)).
45 A call to open() creates a new open file description, an entry in the
47 system-wide table of open files. The open file description records the
48 file offset and the file status flags (see below). A file descriptor
49 is a reference to an open file description; this reference is unaf‐
50 fected if pathname is subsequently removed or modified to refer to a
51 different file. For further details on open file descriptions, see
52 NOTES.
53 The argument flags must include one of the following access modes:
55 O_RDONLY, O_WRONLY, or O_RDWR. These request opening the file read-
56 only, write-only, or read/write, respectively.
57 In addition, zero or more file creation flags and file status flags can
59 be bitwise-or'd in flags. The file creation flags are O_CLOEXEC,
60 O_CREAT, O_DIRECTORY, O_EXCL, O_NOCTTY, O_NOFOLLOW, O_TMPFILE, and
61 O_TRUNC. The file status flags are all of the remaining flags listed
62 below. The distinction between these two groups of flags is that the
63 file creation flags affect the semantics of the open operation itself,
64 while the file status flags affect the semantics of subsequent I/O
65 operations. The file status flags can be retrieved and (in some cases)
66 modified; see fcntl(2) for details.
67 The full list of file creation flags and file status flags is as fol‐
69 lows:
70 O_APPEND
72 The file is opened in append mode. Before each write(2), the
73 file offset is positioned at the end of the file, as if with
74 lseek(2). The modification of the file offset and the write
75 operation are performed as a single atomic step.
76 O_APPEND may lead to corrupted files on NFS filesystems if more
78 than one process appends data to a file at once. This is
79 because NFS does not support appending to a file, so the client
80 kernel has to simulate it, which can't be done without a race
81 condition.
82 O_ASYNC
84 Enable signal-driven I/O: generate a signal (SIGIO by default,
85 but this can be changed via fcntl(2)) when input or output
86 becomes possible on this file descriptor. This feature is
87 available only for terminals, pseudoterminals, sockets, and
88 (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further
89 details. See also BUGS, below.
90 O_CLOEXEC (since Linux 2.6.23)
92 Enable the close-on-exec flag for the new file descriptor.
93 Specifying this flag permits a program to avoid additional
94 fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag.
95 Note that the use of this flag is essential in some multi‐
97 threaded programs, because using a separate fcntl(2) F_SETFD
98 operation to set the FD_CLOEXEC flag does not suffice to avoid
99 race conditions where one thread opens a file descriptor and
100 attempts to set its close-on-exec flag using fcntl(2) at the
101 same time as another thread does a fork(2) plus execve(2).
102 Depending on the order of execution, the race may lead to the
103 file descriptor returned by open() being unintentionally leaked
104 to the program executed by the child process created by fork(2).
105 (This kind of race is in principle possible for any system call
106 that creates a file descriptor whose close-on-exec flag should
107 be set, and various other Linux system calls provide an equiva‐
108 lent of the O_CLOEXEC flag to deal with this problem.)
109 O_CREAT
111 If pathname does not exist, create it as a regular file.
112 The owner (user ID) of the new file is set to the effective user
114 ID of the process.
115 The group ownership (group ID) of the new file is set either to
117 the effective group ID of the process (System V semantics) or to
118 the group ID of the parent directory (BSD semantics). On Linux,
119 the behavior depends on whether the set-group-ID mode bit is set
120 on the parent directory: if that bit is set, then BSD semantics
121 apply; otherwise, System V semantics apply. For some filesys‐
122 tems, the behavior also depends on the bsdgroups and sysvgroups
123 mount options described in mount(8)).
124 The mode argument specifies the file mode bits be applied when a
126 new file is created. This argument must be supplied when
127 O_CREAT or O_TMPFILE is specified in flags; if neither O_CREAT
128 nor O_TMPFILE is specified, then mode is ignored. The effective
129 mode is modified by the process's umask in the usual way: in the
130 absence of a default ACL, the mode of the created file is
131 (mode & ~umask). Note that this mode applies only to future
132 accesses of the newly created file; the open() call that creates
133 a read-only file may well return a read/write file descriptor.
134 The following symbolic constants are provided for mode:
136 S_IRWXU 00700 user (file owner) has read, write, and execute
138 permission
139 S_IRUSR 00400 user has read permission
141 S_IWUSR 00200 user has write permission
143 S_IXUSR 00100 user has execute permission
145 S_IRWXG 00070 group has read, write, and execute permission
147 S_IRGRP 00040 group has read permission
149 S_IWGRP 00020 group has write permission
151 S_IXGRP 00010 group has execute permission
153 S_IRWXO 00007 others have read, write, and execute permission
155 S_IROTH 00004 others have read permission
157 S_IWOTH 00002 others have write permission
159 S_IXOTH 00001 others have execute permission
161 According to POSIX, the effect when other bits are set in mode
163 is unspecified. On Linux, the following bits are also honored
164 in mode:
165 S_ISUID 0004000 set-user-ID bit
167 S_ISGID 0002000 set-group-ID bit (see inode(7)).
169 S_ISVTX 0001000 sticky bit (see inode(7)).
171 O_DIRECT (since Linux 2.4.10)
173 Try to minimize cache effects of the I/O to and from this file.
174 In general this will degrade performance, but it is useful in
175 special situations, such as when applications do their own
176 caching. File I/O is done directly to/from user-space buffers.
177 The O_DIRECT flag on its own makes an effort to transfer data
178 synchronously, but does not give the guarantees of the O_SYNC
179 flag that data and necessary metadata are transferred. To guar‐
180 antee synchronous I/O, O_SYNC must be used in addition to
181 O_DIRECT. See NOTES below for further discussion.
182 A semantically similar (but deprecated) interface for block
184 devices is described in raw(8).
185 O_DIRECTORY
187 If pathname is not a directory, cause the open to fail. This
188 flag was added in kernel version 2.1.126, to avoid denial-of-
189 service problems if opendir(3) is called on a FIFO or tape
190 device.
191 O_DSYNC
193 Write operations on the file will complete according to the
194 requirements of synchronized I/O data integrity completion.
195 By the time write(2) (and similar) return, the output data has
197 been transferred to the underlying hardware, along with any file
198 metadata that would be required to retrieve that data (i.e., as
199 though each write(2) was followed by a call to fdatasync(2)).
200 See NOTES below.
201 O_EXCL Ensure that this call creates the file: if this flag is speci‐
203 fied in conjunction with O_CREAT, and pathname already exists,
204 then open() fails with the error EEXIST.
205 When these two flags are specified, symbolic links are not fol‐
207 lowed: if pathname is a symbolic link, then open() fails regard‐
208 less of where the symbolic link points.
209 In general, the behavior of O_EXCL is undefined if it is used
211 without O_CREAT. There is one exception: on Linux 2.6 and
212 later, O_EXCL can be used without O_CREAT if pathname refers to
213 a block device. If the block device is in use by the system
214 (e.g., mounted), open() fails with the error EBUSY.
215 On NFS, O_EXCL is supported only when using NFSv3 or later on
217 kernel 2.6 or later. In NFS environments where O_EXCL support
218 is not provided, programs that rely on it for performing locking
219 tasks will contain a race condition. Portable programs that
220 want to perform atomic file locking using a lockfile, and need
221 to avoid reliance on NFS support for O_EXCL, can create a unique
222 file on the same filesystem (e.g., incorporating hostname and
223 PID), and use link(2) to make a link to the lockfile. If
224 link(2) returns 0, the lock is successful. Otherwise, use
225 stat(2) on the unique file to check if its link count has
226 increased to 2, in which case the lock is also successful.
227 O_LARGEFILE
229 (LFS) Allow files whose sizes cannot be represented in an off_t
230 (but can be represented in an off64_t) to be opened. The
231 _LARGEFILE64_SOURCE macro must be defined (before including any
232 header files) in order to obtain this definition. Setting the
233 _FILE_OFFSET_BITS feature test macro to 64 (rather than using
234 O_LARGEFILE) is the preferred method of accessing large files on
235 32-bit systems (see feature_test_macros(7)).
236 O_NOATIME (since Linux 2.6.8)
238 Do not update the file last access time (st_atime in the inode)
239 when the file is read(2).
240 This flag can be employed only if one of the following condi‐
242 tions is true:
243 * The effective UID of the process matches the owner UID of the
245 file.
246 * The calling process has the CAP_FOWNER capability in its user
248 namespace and the owner UID of the file has a mapping in the
249 namespace.
250 This flag is intended for use by indexing or backup programs,
252 where its use can significantly reduce the amount of disk activ‐
253 ity. This flag may not be effective on all filesystems. One
254 example is NFS, where the server maintains the access time.
255 O_NOCTTY
257 If pathname refers to a terminal device—see tty(4)—it will not
258 become the process's controlling terminal even if the process
259 does not have one.
260 O_NOFOLLOW
262 If pathname is a symbolic link, then the open fails, with the
263 error ELOOP. Symbolic links in earlier components of the path‐
264 name will still be followed. (Note that the ELOOP error that
265 can occur in this case is indistinguishable from the case where
266 an open fails because there are too many symbolic links found
267 while resolving components in the prefix part of the pathname.)
268 This flag is a FreeBSD extension, which was added to Linux in
270 version 2.1.126, and has subsequently been standardized in
271 POSIX.1-2008.
272 See also O_PATH below.
274 O_NONBLOCK or O_NDELAY
276 When possible, the file is opened in nonblocking mode. Neither
277 the open() nor any subsequent I/O operations on the file
278 descriptor which is returned will cause the calling process to
279 wait.
280 Note that the setting of this flag has no effect on the opera‐
282 tion of poll(2), select(2), epoll(7), and similar, since those
283 interfaces merely inform the caller about whether a file
284 descriptor is "ready", meaning that an I/O operation performed
285 on the file descriptor with the O_NONBLOCK flag clear would not
286 block.
287 Note that this flag has no effect for regular files and block
289 devices; that is, I/O operations will (briefly) block when
290 device activity is required, regardless of whether O_NONBLOCK is
291 set. Since O_NONBLOCK semantics might eventually be imple‐
292 mented, applications should not depend upon blocking behavior
293 when specifying this flag for regular files and block devices.
294 For the handling of FIFOs (named pipes), see also fifo(7). For
296 a discussion of the effect of O_NONBLOCK in conjunction with
297 mandatory file locks and with file leases, see fcntl(2).
298 O_PATH (since Linux 2.6.39)
300 Obtain a file descriptor that can be used for two purposes: to
301 indicate a location in the filesystem tree and to perform opera‐
302 tions that act purely at the file descriptor level. The file
303 itself is not opened, and other file operations (e.g., read(2),
304 write(2), fchmod(2), fchown(2), fgetxattr(2), ioctl(2), mmap(2))
305 fail with the error EBADF.
306 The following operations can be performed on the resulting file
308 descriptor:
309 * close(2).
311 * fchdir(2), if the file descriptor refers to a directory
313 (since Linux 3.5).
314 * fstat(2) (since Linux 3.6).
316 * fstatfs(2) (since Linux 3.12).
318 * Duplicating the file descriptor (dup(2), fcntl(2) F_DUPFD,
320 etc.).
321 * Getting and setting file descriptor flags (fcntl(2) F_GETFD
323 and F_SETFD).
324 * Retrieving open file status flags using the fcntl(2) F_GETFL
326 operation: the returned flags will include the bit O_PATH.
327 * Passing the file descriptor as the dirfd argument of openat()
329 and the other "*at()" system calls. This includes linkat(2)
330 with AT_EMPTY_PATH (or via procfs using AT_SYMLINK_FOLLOW)
331 even if the file is not a directory.
332 * Passing the file descriptor to another process via a UNIX
334 domain socket (see SCM_RIGHTS in unix(7)).
335 When O_PATH is specified in flags, flag bits other than
337 O_CLOEXEC, O_DIRECTORY, and O_NOFOLLOW are ignored.
338 Opening a file or directory with the O_PATH flag requires no
340 permissions on the object itself (but does require execute per‐
341 mission on the directories in the path prefix). Depending on
342 the subsequent operation, a check for suitable file permissions
343 may be performed (e.g., fchdir(2) requires execute permission on
344 the directory referred to by its file descriptor argument). By
345 contrast, obtaining a reference to a filesystem object by open‐
346 ing it with the O_RDONLY flag requires that the caller have read
347 permission on the object, even when the subsequent operation
348 (e.g., fchdir(2), fstat(2)) does not require read permission on
349 the object.
350 If pathname is a symbolic link and the O_NOFOLLOW flag is also
352 specified, then the call returns a file descriptor referring to
353 the symbolic link. This file descriptor can be used as the
354 dirfd argument in calls to fchownat(2), fstatat(2), linkat(2),
355 and readlinkat(2) with an empty pathname to have the calls oper‐
356 ate on the symbolic link.
357 If pathname refers to an automount point that has not yet been
359 triggered, so no other filesystem is mounted on it, then the
360 call returns a file descriptor referring to the automount direc‐
361 tory without triggering a mount. fstatfs(2) can then be used to
362 determine if it is, in fact, an untriggered automount point
363 (.f_type == AUTOFS_SUPER_MAGIC).
364 One use of O_PATH for regular files is to provide the equivalent
366 of POSIX.1's O_EXEC functionality. This permits us to open a
367 file for which we have execute permission but not read permis‐
368 sion, and then execute that file, with steps something like the
369 following:
370 char buf[PATH_MAX];
372 fd = open("some_prog", O_PATH);
373 snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd);
374 execl(buf, "some_prog", (char *) NULL);
375 An O_PATH file descriptor can also be passed as the argument of
377 fexecve(3).
378 O_SYNC Write operations on the file will complete according to the
380 requirements of synchronized I/O file integrity completion (by
381 contrast with the synchronized I/O data integrity completion
382 provided by O_DSYNC.)
383 By the time write(2) (or similar) returns, the output data and
385 associated file metadata have been transferred to the underlying
386 hardware (i.e., as though each write(2) was followed by a call
387 to fsync(2)). See NOTES below.
388 O_TMPFILE (since Linux 3.11)
390 Create an unnamed temporary regular file. The pathname argument
391 specifies a directory; an unnamed inode will be created in that
392 directory's filesystem. Anything written to the resulting file
393 will be lost when the last file descriptor is closed, unless the
394 file is given a name.
395 O_TMPFILE must be specified with one of O_RDWR or O_WRONLY and,
397 optionally, O_EXCL. If O_EXCL is not specified, then linkat(2)
398 can be used to link the temporary file into the filesystem, mak‐
399 ing it permanent, using code like the following:
400 char path[PATH_MAX];
402 fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
403 S_IRUSR | S_IWUSR);
404 /* File I/O on 'fd'... */
406 snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd);
408 linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
409 AT_SYMLINK_FOLLOW);
410 In this case, the open() mode argument determines the file per‐
412 mission mode, as with O_CREAT.
413 Specifying O_EXCL in conjunction with O_TMPFILE prevents a tem‐
415 porary file from being linked into the filesystem in the above
416 manner. (Note that the meaning of O_EXCL in this case is dif‐
417 ferent from the meaning of O_EXCL otherwise.)
418 There are two main use cases for O_TMPFILE:
420 * Improved tmpfile(3) functionality: race-free creation of tem‐
422 porary files that (1) are automatically deleted when closed;
423 (2) can never be reached via any pathname; (3) are not sub‐
424 ject to symlink attacks; and (4) do not require the caller to
425 devise unique names.
426 * Creating a file that is initially invisible, which is then
428 populated with data and adjusted to have appropriate filesys‐
429 tem attributes (fchown(2), fchmod(2), fsetxattr(2), etc.)
430 before being atomically linked into the filesystem in a fully
431 formed state (using linkat(2) as described above).
432 O_TMPFILE requires support by the underlying filesystem; only a
434 subset of Linux filesystems provide that support. In the ini‐
435 tial implementation, support was provided in the ext2, ext3,
436 ext4, UDF, Minix, and shmem filesystems. Support for other
437 filesystems has subsequently been added as follows: XFS (Linux
438 3.15); Btrfs (Linux 3.16); F2FS (Linux 3.16); and ubifs (Linux
439 4.9)
440 O_TRUNC
442 If the file already exists and is a regular file and the access
443 mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be
444 truncated to length 0. If the file is a FIFO or terminal device
445 file, the O_TRUNC flag is ignored. Otherwise, the effect of
446 O_TRUNC is unspecified.
447 creat()
449 A call to creat() is equivalent to calling open() with flags equal to
450 O_CREAT|O_WRONLY|O_TRUNC.
451 openat()
453 The openat() system call operates in exactly the same way as open(),
454 except for the differences described here.
455 If the pathname given in pathname is relative, then it is interpreted
457 relative to the directory referred to by the file descriptor dirfd
458 (rather than relative to the current working directory of the calling
459 process, as is done by open() for a relative pathname).
460 If pathname is relative and dirfd is the special value AT_FDCWD, then
462 pathname is interpreted relative to the current working directory of
463 the calling process (like open()).
464 If pathname is absolute, then dirfd is ignored.
466
468 open(), openat(), and creat() return the new file descriptor, or -1 if
469 an error occurred (in which case, errno is set appropriately).
470
472 open(), openat(), and creat() can fail with the following errors:
473 EACCES The requested access to the file is not allowed, or search per‐
475 mission is denied for one of the directories in the path prefix
476 of pathname, or the file did not exist yet and write access to
477 the parent directory is not allowed. (See also path_resolu‐
478 tion(7).)
479 EDQUOT Where O_CREAT is specified, the file does not exist, and the
481 user's quota of disk blocks or inodes on the filesystem has been
482 exhausted.
483 EEXIST pathname already exists and O_CREAT and O_EXCL were used.
485 EFAULT pathname points outside your accessible address space.
487 EFBIG See EOVERFLOW.
489 EINTR While blocked waiting to complete an open of a slow device
491 (e.g., a FIFO; see fifo(7)), the call was interrupted by a sig‐
492 nal handler; see signal(7).
493 EINVAL The filesystem does not support the O_DIRECT flag. See NOTES
495 for more information.
496 EINVAL Invalid value in flags.
498 EINVAL O_TMPFILE was specified in flags, but neither O_WRONLY nor
500 O_RDWR was specified.
501 EINVAL O_CREAT was specified in flags and the final component ("base‐
503 name") of the new file's pathname is invalid (e.g., it contains
504 characters not permitted by the underlying filesystem).
505 EISDIR pathname refers to a directory and the access requested involved
507 writing (that is, O_WRONLY or O_RDWR is set).
508 EISDIR pathname refers to an existing directory, O_TMPFILE and one of
510 O_WRONLY or O_RDWR were specified in flags, but this kernel ver‐
511 sion does not provide the O_TMPFILE functionality.
512 ELOOP Too many symbolic links were encountered in resolving pathname.
514 ELOOP pathname was a symbolic link, and flags specified O_NOFOLLOW but
516 not O_PATH.
517 EMFILE The per-process limit on the number of open file descriptors has
519 been reached (see the description of RLIMIT_NOFILE in getr‐
520 limit(2)).
521 ENAMETOOLONG
523 pathname was too long.
524 ENFILE The system-wide limit on the total number of open files has been
526 reached.
527 ENODEV pathname refers to a device special file and no corresponding
529 device exists. (This is a Linux kernel bug; in this situation
530 ENXIO must be returned.)
531 ENOENT O_CREAT is not set and the named file does not exist.
533 ENOENT A directory component in pathname does not exist or is a dan‐
535 gling symbolic link.
536 ENOENT pathname refers to a nonexistent directory, O_TMPFILE and one of
538 O_WRONLY or O_RDWR were specified in flags, but this kernel ver‐
539 sion does not provide the O_TMPFILE functionality.
540 ENOMEM The named file is a FIFO, but memory for the FIFO buffer can't
542 be allocated because the per-user hard limit on memory alloca‐
543 tion for pipes has been reached and the caller is not privi‐
544 leged; see pipe(7).
545 ENOMEM Insufficient kernel memory was available.
547 ENOSPC pathname was to be created but the device containing pathname
549 has no room for the new file.
550 ENOTDIR
552 A component used as a directory in pathname is not, in fact, a
553 directory, or O_DIRECTORY was specified and pathname was not a
554 directory.
555 ENXIO O_NONBLOCK | O_WRONLY is set, the named file is a FIFO, and no
557 process has the FIFO open for reading.
558 ENXIO The file is a device special file and no corresponding device
560 exists.
561 ENXIO The file is a UNIX domain socket.
563 EOPNOTSUPP
565 The filesystem containing pathname does not support O_TMPFILE.
566 EOVERFLOW
568 pathname refers to a regular file that is too large to be
569 opened. The usual scenario here is that an application compiled
570 on a 32-bit platform without -D_FILE_OFFSET_BITS=64 tried to
571 open a file whose size exceeds (1<<31)-1 bytes; see also
572 O_LARGEFILE above. This is the error specified by POSIX.1; in
573 kernels before 2.6.24, Linux gave the error EFBIG for this case.
574 EPERM The O_NOATIME flag was specified, but the effective user ID of
576 the caller did not match the owner of the file and the caller
577 was not privileged.
578 EPERM The operation was prevented by a file seal; see fcntl(2).
580 EROFS pathname refers to a file on a read-only filesystem and write
582 access was requested.
583 ETXTBSY
585 pathname refers to an executable image which is currently being
586 executed and write access was requested.
587 ETXTBSY
589 pathname refers to a file that is currently in use as a swap
590 file, and the O_TRUNC flag was specified.
591 ETXTBSY
593 pathname refers to a file that is currently being read by the
594 kernel (e.g. for module/firmware loading), and write access was
595 requested.
596 EWOULDBLOCK
598 The O_NONBLOCK flag was specified, and an incompatible lease was
599 held on the file (see fcntl(2)).
600 The following additional errors can occur for openat():
602 EBADF dirfd is not a valid file descriptor.
604 ENOTDIR
606 pathname is a relative pathname and dirfd is a file descriptor
607 referring to a file other than a directory.
608
610 openat() was added to Linux in kernel 2.6.16; library support was added
611 to glibc in version 2.4.
612
614 open(), creat() SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
615 openat(): POSIX.1-2008.
617 The O_DIRECT, O_NOATIME, O_PATH, and O_TMPFILE flags are Linux-spe‐
619 cific. One must define _GNU_SOURCE to obtain their definitions.
620 The O_CLOEXEC, O_DIRECTORY, and O_NOFOLLOW flags are not specified in
622 POSIX.1-2001, but are specified in POSIX.1-2008. Since glibc 2.12, one
623 can obtain their definitions by defining either _POSIX_C_SOURCE with a
624 value greater than or equal to 200809L or _XOPEN_SOURCE with a value
625 greater than or equal to 700. In glibc 2.11 and earlier, one obtains
626 the definitions by defining _GNU_SOURCE.
627 As noted in feature_test_macros(7), feature test macros such as
629 _POSIX_C_SOURCE, _XOPEN_SOURCE, and _GNU_SOURCE must be defined before
630 including any header files.
631
633 Under Linux, the O_NONBLOCK flag is sometimes used in cases where one
634 wants to open but does not necessarily have the intention to read or
635 write. For example, this may be used to open a device in order to get
636 a file descriptor for use with ioctl(2).
637 The (undefined) effect of O_RDONLY | O_TRUNC varies among implementa‐
639 tions. On many systems the file is actually truncated.
640 Note that open() can open device special files, but creat() cannot cre‐
642 ate them; use mknod(2) instead.
643 If the file is newly created, its st_atime, st_ctime, st_mtime fields
645 (respectively, time of last access, time of last status change, and
646 time of last modification; see stat(2)) are set to the current time,
647 and so are the st_ctime and st_mtime fields of the parent directory.
648 Otherwise, if the file is modified because of the O_TRUNC flag, its
649 st_ctime and st_mtime fields are set to the current time.
650 The files in the /proc/[pid]/fd directory show the open file descrip‐
652 tors of the process with the PID pid. The files in the
653 /proc/[pid]/fdinfo directory show even more information about these
654 file descriptors. See proc(5) for further details of both of these
655 directories.
656 The Linux header file <asm/fcntl.h> doesn't define O_ASYNC; the (BSD-
658 derived) FASYNC synonym is defined instead.
659 Open file descriptions
661 The term open file description is the one used by POSIX to refer to the
662 entries in the system-wide table of open files. In other contexts,
663 this object is variously also called an "open file object", a "file
664 handle", an "open file table entry", or—in kernel-developer parlance—a
665 struct file.
666 When a file descriptor is duplicated (using dup(2) or similar), the
668 duplicate refers to the same open file description as the original file
669 descriptor, and the two file descriptors consequently share the file
670 offset and file status flags. Such sharing can also occur between pro‐
671 cesses: a child process created via fork(2) inherits duplicates of its
672 parent's file descriptors, and those duplicates refer to the same open
673 file descriptions.
674 Each open() of a file creates a new open file description; thus, there
676 may be multiple open file descriptions corresponding to a file inode.
677 On Linux, one can use the kcmp(2) KCMP_FILE operation to test whether
679 two file descriptors (in the same process or in two different pro‐
680 cesses) refer to the same open file description.
681 Synchronized I/O
683 The POSIX.1-2008 "synchronized I/O" option specifies different variants
684 of synchronized I/O, and specifies the open() flags O_SYNC, O_DSYNC,
685 and O_RSYNC for controlling the behavior. Regardless of whether an
686 implementation supports this option, it must at least support the use
687 of O_SYNC for regular files.
688 Linux implements O_SYNC and O_DSYNC, but not O_RSYNC. Somewhat incor‐
690 rectly, glibc defines O_RSYNC to have the same value as O_SYNC.
691 (O_RSYNC is defined in the Linux header file <asm/fcntl.h> on HP PA-
692 RISC, but it is not used.)
693 O_SYNC provides synchronized I/O file integrity completion, meaning
695 write operations will flush data and all associated metadata to the
696 underlying hardware. O_DSYNC provides synchronized I/O data integrity
697 completion, meaning write operations will flush data to the underlying
698 hardware, but will only flush metadata updates that are required to
699 allow a subsequent read operation to complete successfully. Data
700 integrity completion can reduce the number of disk operations that are
701 required for applications that don't need the guarantees of file
702 integrity completion.
703 To understand the difference between the two types of completion, con‐
705 sider two pieces of file metadata: the file last modification timestamp
706 (st_mtime) and the file length. All write operations will update the
707 last file modification timestamp, but only writes that add data to the
708 end of the file will change the file length. The last modification
709 timestamp is not needed to ensure that a read completes successfully,
710 but the file length is. Thus, O_DSYNC would only guarantee to flush
711 updates to the file length metadata (whereas O_SYNC would also always
712 flush the last modification timestamp metadata).
713 Before Linux 2.6.33, Linux implemented only the O_SYNC flag for open().
715 However, when that flag was specified, most filesystems actually pro‐
716 vided the equivalent of synchronized I/O data integrity completion
717 (i.e., O_SYNC was actually implemented as the equivalent of O_DSYNC).
718 Since Linux 2.6.33, proper O_SYNC support is provided. However, to
720 ensure backward binary compatibility, O_DSYNC was defined with the same
721 value as the historical O_SYNC, and O_SYNC was defined as a new (two-
722 bit) flag value that includes the O_DSYNC flag value. This ensures
723 that applications compiled against new headers get at least O_DSYNC
724 semantics on pre-2.6.33 kernels.
725 C library/kernel differences
727 Since version 2.26, the glibc wrapper function for open() employs the
728 openat() system call, rather than the kernel's open() system call. For
729 certain architectures, this is also true in glibc versions before 2.26.
730 NFS
732 There are many infelicities in the protocol underlying NFS, affecting
733 amongst others O_SYNC and O_NDELAY.
734 On NFS filesystems with UID mapping enabled, open() may return a file
736 descriptor but, for example, read(2) requests are denied with EACCES.
737 This is because the client performs open() by checking the permissions,
738 but UID mapping is performed by the server upon read and write
739 requests.
740 FIFOs
742 Opening the read or write end of a FIFO blocks until the other end is
743 also opened (by another process or thread). See fifo(7) for further
744 details.
745 File access mode
747 Unlike the other values that can be specified in flags, the access mode
748 values O_RDONLY, O_WRONLY, and O_RDWR do not specify individual bits.
749 Rather, they define the low order two bits of flags, and are defined
750 respectively as 0, 1, and 2. In other words, the combination O_RDONLY
751 | O_WRONLY is a logical error, and certainly does not have the same
752 meaning as O_RDWR.
753 Linux reserves the special, nonstandard access mode 3 (binary 11) in
755 flags to mean: check for read and write permission on the file and
756 return a file descriptor that can't be used for reading or writing.
757 This nonstandard access mode is used by some Linux drivers to return a
758 file descriptor that is to be used only for device-specific ioctl(2)
759 operations.
760 Rationale for openat() and other directory file descriptor APIs
762 openat() and the other system calls and library functions that take a
763 directory file descriptor argument (i.e., execveat(2), faccessat(2),
764 fanotify_mark(2), fchmodat(2), fchownat(2), fstatat(2), futimesat(2),
765 linkat(2), mkdirat(2), mknodat(2), name_to_handle_at(2), readlinkat(2),
766 renameat(2), statx(2), symlinkat(2), unlinkat(2), utimensat(2), mkfi‐
767 foat(3), and scandirat(3)) address two problems with the older inter‐
768 faces that preceded them. Here, the explanation is in terms of the
769 openat() call, but the rationale is analogous for the other interfaces.
770 First, openat() allows an application to avoid race conditions that
772 could occur when using open() to open files in directories other than
773 the current working directory. These race conditions result from the
774 fact that some component of the directory prefix given to open() could
775 be changed in parallel with the call to open(). Suppose, for example,
776 that we wish to create the file dir1/dir2/xxx.dep if the file
777 dir1/dir2/xxx exists. The problem is that between the existence check
778 and the file-creation step, dir1 or dir2 (which might be symbolic
779 links) could be modified to point to a different location. Such races
780 can be avoided by opening a file descriptor for the target directory,
781 and then specifying that file descriptor as the dirfd argument of (say)
782 fstatat(2) and openat(). The use of the dirfd file descriptor also has
783 other benefits:
784 * the file descriptor is a stable reference to the directory, even if
786 the directory is renamed; and
787 * the open file descriptor prevents the underlying filesystem from
789 being dismounted, just as when a process has a current working
790 directory on a filesystem.
791 Second, openat() allows the implementation of a per-thread "current
793 working directory", via file descriptor(s) maintained by the applica‐
794 tion. (This functionality can also be obtained by tricks based on the
795 use of /proc/self/fd/dirfd, but less efficiently.)
796 O_DIRECT
798 The O_DIRECT flag may impose alignment restrictions on the length and
799 address of user-space buffers and the file offset of I/Os. In Linux
800 alignment restrictions vary by filesystem and kernel version and might
801 be absent entirely. However there is currently no filesystem-indepen‐
802 dent interface for an application to discover these restrictions for a
803 given file or filesystem. Some filesystems provide their own inter‐
804 faces for doing so, for example the XFS_IOC_DIOINFO operation in
805 xfsctl(3).
806 Under Linux 2.4, transfer sizes, and the alignment of the user buffer
808 and the file offset must all be multiples of the logical block size of
809 the filesystem. Since Linux 2.6.0, alignment to the logical block size
810 of the underlying storage (typically 512 bytes) suffices. The logical
811 block size can be determined using the ioctl(2) BLKSSZGET operation or
812 from the shell using the command:
813 blockdev --getss
815 O_DIRECT I/Os should never be run concurrently with the fork(2) system
817 call, if the memory buffer is a private mapping (i.e., any mapping cre‐
818 ated with the mmap(2) MAP_PRIVATE flag; this includes memory allocated
819 on the heap and statically allocated buffers). Any such I/Os, whether
820 submitted via an asynchronous I/O interface or from another thread in
821 the process, should be completed before fork(2) is called. Failure to
822 do so can result in data corruption and undefined behavior in parent
823 and child processes. This restriction does not apply when the memory
824 buffer for the O_DIRECT I/Os was created using shmat(2) or mmap(2) with
825 the MAP_SHARED flag. Nor does this restriction apply when the memory
826 buffer has been advised as MADV_DONTFORK with madvise(2), ensuring that
827 it will not be available to the child after fork(2).
828 The O_DIRECT flag was introduced in SGI IRIX, where it has alignment
830 restrictions similar to those of Linux 2.4. IRIX has also a fcntl(2)
831 call to query appropriate alignments, and sizes. FreeBSD 4.x intro‐
832 duced a flag of the same name, but without alignment restrictions.
833 O_DIRECT support was added under Linux in kernel version 2.4.10. Older
835 Linux kernels simply ignore this flag. Some filesystems may not imple‐
836 ment the flag, in which case open() fails with the error EINVAL if it
837 is used.
838 Applications should avoid mixing O_DIRECT and normal I/O to the same
840 file, and especially to overlapping byte regions in the same file.
841 Even when the filesystem correctly handles the coherency issues in this
842 situation, overall I/O throughput is likely to be slower than using
843 either mode alone. Likewise, applications should avoid mixing mmap(2)
844 of files with direct I/O to the same files.
845 The behavior of O_DIRECT with NFS will differ from local filesystems.
847 Older kernels, or kernels configured in certain ways, may not support
848 this combination. The NFS protocol does not support passing the flag
849 to the server, so O_DIRECT I/O will bypass the page cache only on the
850 client; the server may still cache the I/O. The client asks the server
851 to make the I/O synchronous to preserve the synchronous semantics of
852 O_DIRECT. Some servers will perform poorly under these circumstances,
853 especially if the I/O size is small. Some servers may also be config‐
854 ured to lie to clients about the I/O having reached stable storage;
855 this will avoid the performance penalty at some risk to data integrity
856 in the event of server power failure. The Linux NFS client places no
857 alignment restrictions on O_DIRECT I/O.
858 In summary, O_DIRECT is a potentially powerful tool that should be used
860 with caution. It is recommended that applications treat use of
861 O_DIRECT as a performance option which is disabled by default.
862
864 Currently, it is not possible to enable signal-driven I/O by specifying
865 O_ASYNC when calling open(); use fcntl(2) to enable this flag.
866 One must check for two different error codes, EISDIR and ENOENT, when
868 trying to determine whether the kernel supports O_TMPFILE functional‐
869 ity.
870 When both O_CREAT and O_DIRECTORY are specified in flags and the file
872 specified by pathname does not exist, open() will create a regular file
873 (i.e., O_DIRECTORY is ignored).
874
876 chmod(2), chown(2), close(2), dup(2), fcntl(2), link(2), lseek(2),
877 mknod(2), mmap(2), mount(2), open_by_handle_at(2), read(2), socket(2),
878 stat(2), umask(2), unlink(2), write(2), fopen(3), acl(5), fifo(7),
879 inode(7), path_resolution(7), symlink(7)
880
882 This page is part of release 5.04 of the Linux man-pages project. A
883 description of the project, information about reporting bugs, and the
884 latest version of this page, can be found at
885 https://www.kernel.org/doc/man-pages/.
886Linux 2018-04-30 OPEN(2)