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