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