1OPEN(2)                    Linux Programmer's Manual                   OPEN(2)
2
3
4

NAME

6       open, openat, creat - open and possibly create a file
7

SYNOPSIS

9       #include <fcntl.h>
10
11       int open(const char *pathname, int flags);
12       int open(const char *pathname, int flags, mode_t mode);
13
14       int creat(const char *pathname, mode_t mode);
15
16       int openat(int dirfd, const char *pathname, int flags);
17       int openat(int dirfd, const char *pathname, int flags, mode_t mode);
18
19       /* Documented separately, in openat2(2): */
20       int openat2(int dirfd, const char *pathname,
21                   const struct open_how *how, size_t size);
22
23   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
24
25       openat():
26           Since glibc 2.10:
27               _POSIX_C_SOURCE >= 200809L
28           Before glibc 2.10:
29               _ATFILE_SOURCE
30

DESCRIPTION

32       The  open()  system  call opens the file specified by pathname.  If the
33       specified file does not exist, it may optionally (if O_CREAT is  speci‐
34       fied in flags) be created by open().
35
36       The  return  value of open() is a file descriptor, a small, nonnegative
37       integer that is an index to an entry in the  process's  table  of  open
38       file  descriptors.   The  file  descriptor is used in subsequent system
39       calls (read(2), write(2), lseek(2), fcntl(2), etc.)  to  refer  to  the
40       open  file.   The file descriptor returned by a successful call will be
41       the lowest-numbered file descriptor not currently open for the process.
42
43       By default, the new file descriptor is set to remain open across an ex‐
44       ecve(2)  (i.e.,  the  FD_CLOEXEC  file descriptor flag described in fc‐
45       ntl(2) is initially disabled); the O_CLOEXEC flag, described below, can
46       be  used  to change this default.  The file offset is set to the begin‐
47       ning of the file (see lseek(2)).
48
49       A call to open() creates a new open file description, an entry  in  the
50       system-wide table of open files.  The open file description records the
51       file offset and the file status flags (see below).  A  file  descriptor
52       is  a  reference  to  an open file description; this reference is unaf‐
53       fected if pathname is subsequently removed or modified to  refer  to  a
54       different  file.   For  further  details on open file descriptions, see
55       NOTES.
56
57       The argument flags must include one  of  the  following  access  modes:
58       O_RDONLY,  O_WRONLY,  or  O_RDWR.  These request opening the file read-
59       only, write-only, or read/write, respectively.
60
61       In addition, zero or more file creation flags and file status flags can
62       be  bitwise-or'd  in  flags.   The  file  creation flags are O_CLOEXEC,
63       O_CREAT, O_DIRECTORY,  O_EXCL,  O_NOCTTY,  O_NOFOLLOW,  O_TMPFILE,  and
64       O_TRUNC.   The  file status flags are all of the remaining flags listed
65       below.  The distinction between these two groups of flags is  that  the
66       file  creation flags affect the semantics of the open operation itself,
67       while the file status flags affect the semantics of subsequent I/O  op‐
68       erations.   The  file status flags can be retrieved and (in some cases)
69       modified; see fcntl(2) for details.
70
71       The full list of file creation flags and file status flags is  as  fol‐
72       lows:
73
74       O_APPEND
75              The  file  is  opened in append mode.  Before each write(2), the
76              file offset is positioned at the end of the  file,  as  if  with
77              lseek(2).  The modification of the file offset and the write op‐
78              eration are performed as a single atomic step.
79
80              O_APPEND may lead to corrupted files on NFS filesystems if  more
81              than  one  process  appends data to a file at once.  This is be‐
82              cause NFS does not support appending to a file,  so  the  client
83              kernel  has  to  simulate it, which can't be done without a race
84              condition.
85
86       O_ASYNC
87              Enable signal-driven I/O: generate a signal (SIGIO  by  default,
88              but  this  can be changed via fcntl(2)) when input or output be‐
89              comes possible on this file descriptor.  This feature is  avail‐
90              able  only  for  terminals, pseudoterminals, sockets, and (since
91              Linux 2.6) pipes and FIFOs.  See fcntl(2) for  further  details.
92              See also BUGS, below.
93
94       O_CLOEXEC (since Linux 2.6.23)
95              Enable  the  close-on-exec  flag  for  the  new file descriptor.
96              Specifying this flag permits a program to avoid  additional  fc‐
97              ntl(2) F_SETFD operations to set the FD_CLOEXEC flag.
98
99              Note  that  the  use  of  this  flag is essential in some multi‐
100              threaded programs, because using a separate fcntl(2) F_SETFD op‐
101              eration  to  set  the  FD_CLOEXEC flag does not suffice to avoid
102              race conditions where one thread opens a file descriptor and at‐
103              tempts  to set its close-on-exec flag using fcntl(2) at the same
104              time as another thread does a fork(2) plus execve(2).  Depending
105              on  the  order  of  execution, the race may lead to the file de‐
106              scriptor returned by open() being unintentionally leaked to  the
107              program executed by the child process created by fork(2).  (This
108              kind of race is in principle possible for any system  call  that
109              creates  a  file  descriptor  whose close-on-exec flag should be
110              set, and various other Linux system calls provide an  equivalent
111              of the O_CLOEXEC flag to deal with this problem.)
112
113       O_CREAT
114              If pathname does not exist, create it as a regular file.
115
116              The owner (user ID) of the new file is set to the effective user
117              ID of the process.
118
119              The group ownership (group ID) of the new file is set either  to
120              the effective group ID of the process (System V semantics) or to
121              the group ID of the parent directory (BSD semantics).  On Linux,
122              the behavior depends on whether the set-group-ID mode bit is set
123              on the parent directory: if that bit is set, then BSD  semantics
124              apply;  otherwise,  System V semantics apply.  For some filesys‐
125              tems, the behavior also depends on the bsdgroups and  sysvgroups
126              mount options described in mount(8).
127
128              The  mode  argument  specifies  the file mode bits to be applied
129              when a new file is created.  If neither O_CREAT nor O_TMPFILE is
130              specified in flags, then mode is ignored (and can thus be speci‐
131              fied as 0, or simply omitted).  The mode argument must  be  sup‐
132              plied  if  O_CREAT  or O_TMPFILE is specified in flags; if it is
133              not supplied, some arbitrary bytes from the stack  will  be  ap‐
134              plied as the file mode.
135
136              The  effective  mode  is  modified by the process's umask in the
137              usual way: in the absence of a default ACL, the mode of the cre‐
138              ated file is (mode & ~umask).
139
140              Note that mode applies only to future accesses of the newly cre‐
141              ated file; the open() call that creates  a  read-only  file  may
142              well return a read/write file descriptor.
143
144              The following symbolic constants are provided for mode:
145
146              S_IRWXU  00700  user  (file  owner) has read, write, and execute
147                       permission
148
149              S_IRUSR  00400 user has read permission
150
151              S_IWUSR  00200 user has write permission
152
153              S_IXUSR  00100 user has execute permission
154
155              S_IRWXG  00070 group has read, write, and execute permission
156
157              S_IRGRP  00040 group has read permission
158
159              S_IWGRP  00020 group has write permission
160
161              S_IXGRP  00010 group has execute permission
162
163              S_IRWXO  00007 others have read, write, and execute permission
164
165              S_IROTH  00004 others have read permission
166
167              S_IWOTH  00002 others have write permission
168
169              S_IXOTH  00001 others have execute permission
170
171              According to POSIX, the effect when other bits are set  in  mode
172              is  unspecified.   On Linux, the following bits are also honored
173              in mode:
174
175              S_ISUID  0004000 set-user-ID bit
176
177              S_ISGID  0002000 set-group-ID bit (see inode(7)).
178
179              S_ISVTX  0001000 sticky bit (see inode(7)).
180
181       O_DIRECT (since Linux 2.4.10)
182              Try to minimize cache effects of the I/O to and from this  file.
183              In  general  this  will degrade performance, but it is useful in
184              special situations, such  as  when  applications  do  their  own
185              caching.   File I/O is done directly to/from user-space buffers.
186              The O_DIRECT flag on its own makes an effort  to  transfer  data
187              synchronously,  but  does  not give the guarantees of the O_SYNC
188              flag that data and necessary metadata are transferred.  To guar‐
189              antee  synchronous I/O, O_SYNC must be used in addition to O_DI‐
190              RECT.  See NOTES below for further discussion.
191
192              A semantically similar (but deprecated) interface for block  de‐
193              vices is described in raw(8).
194
195       O_DIRECTORY
196              If  pathname  is  not a directory, cause the open to fail.  This
197              flag was added in kernel version 2.1.126,  to  avoid  denial-of-
198              service  problems  if opendir(3) is called on a FIFO or tape de‐
199              vice.
200
201       O_DSYNC
202              Write operations on the file will complete according to the  re‐
203              quirements of synchronized I/O data integrity completion.
204
205              By  the  time write(2) (and similar) return, the output data has
206              been transferred to the underlying hardware, along with any file
207              metadata  that would be required to retrieve that data (i.e., as
208              though each write(2) was followed by a  call  to  fdatasync(2)).
209              See NOTES below.
210
211       O_EXCL Ensure  that  this call creates the file: if this flag is speci‐
212              fied in conjunction with O_CREAT, and pathname  already  exists,
213              then open() fails with the error EEXIST.
214
215              When  these two flags are specified, symbolic links are not fol‐
216              lowed: if pathname is a symbolic link, then open() fails regard‐
217              less of where the symbolic link points.
218
219              In  general,  the  behavior of O_EXCL is undefined if it is used
220              without O_CREAT.  There is  one  exception:  on  Linux  2.6  and
221              later,  O_EXCL can be used without O_CREAT if pathname refers to
222              a block device.  If the block device is in  use  by  the  system
223              (e.g., mounted), open() fails with the error EBUSY.
224
225              On  NFS,  O_EXCL  is supported only when using NFSv3 or later on
226              kernel 2.6 or later.  In NFS environments where  O_EXCL  support
227              is not provided, programs that rely on it for performing locking
228              tasks will contain a race  condition.   Portable  programs  that
229              want  to  perform atomic file locking using a lockfile, and need
230              to avoid reliance on NFS support for O_EXCL, can create a unique
231              file  on  the  same filesystem (e.g., incorporating hostname and
232              PID), and use link(2) to  make  a  link  to  the  lockfile.   If
233              link(2)  returns  0,  the  lock  is  successful.  Otherwise, use
234              stat(2) on the unique file to check if its link  count  has  in‐
235              creased to 2, in which case the lock is also successful.
236
237       O_LARGEFILE
238              (LFS)  Allow files whose sizes cannot be represented in an off_t
239              (but can be represented  in  an  off64_t)  to  be  opened.   The
240              _LARGEFILE64_SOURCE  macro must be defined (before including any
241              header files) in order to obtain this definition.   Setting  the
242              _FILE_OFFSET_BITS  feature  test  macro to 64 (rather than using
243              O_LARGEFILE) is the preferred method of accessing large files on
244              32-bit systems (see feature_test_macros(7)).
245
246       O_NOATIME (since Linux 2.6.8)
247              Do  not update the file last access time (st_atime in the inode)
248              when the file is read(2).
249
250              This flag can be employed only if one of  the  following  condi‐
251              tions is true:
252
253              *  The effective UID of the process matches the owner UID of the
254                 file.
255
256              *  The calling process has the CAP_FOWNER capability in its user
257                 namespace  and the owner UID of the file has a mapping in the
258                 namespace.
259
260              This flag is intended for use by indexing  or  backup  programs,
261              where its use can significantly reduce the amount of disk activ‐
262              ity.  This flag may not be effective on  all  filesystems.   One
263              example is NFS, where the server maintains the access time.
264
265       O_NOCTTY
266              If  pathname  refers to a terminal device—see tty(4)—it will not
267              become the process's controlling terminal even  if  the  process
268              does not have one.
269
270       O_NOFOLLOW
271              If the trailing component (i.e., basename) of pathname is a sym‐
272              bolic link, then the open fails, with the error ELOOP.  Symbolic
273              links  in  earlier components of the pathname will still be fol‐
274              lowed.  (Note that the ELOOP error that can occur in  this  case
275              is  indistinguishable  from the case where an open fails because
276              there are too many symbolic links found while  resolving  compo‐
277              nents in the prefix part of the pathname.)
278
279              This  flag  is  a FreeBSD extension, which was added to Linux in
280              version 2.1.126,  and  has  subsequently  been  standardized  in
281              POSIX.1-2008.
282
283              See also O_PATH below.
284
285       O_NONBLOCK or O_NDELAY
286              When  possible, the file is opened in nonblocking mode.  Neither
287              the open() nor any subsequent I/O operations  on  the  file  de‐
288              scriptor  which  is  returned  will cause the calling process to
289              wait.
290
291              Note that the setting of this flag has no effect on  the  opera‐
292              tion  of  poll(2), select(2), epoll(7), and similar, since those
293              interfaces merely inform the caller about  whether  a  file  de‐
294              scriptor  is "ready", meaning that an I/O operation performed on
295              the file descriptor with the O_NONBLOCK  flag  clear  would  not
296              block.
297
298              Note  that  this  flag has no effect for regular files and block
299              devices; that is, I/O operations will (briefly) block  when  de‐
300              vice  activity  is required, regardless of whether O_NONBLOCK is
301              set.  Since O_NONBLOCK  semantics  might  eventually  be  imple‐
302              mented,  applications  should  not depend upon blocking behavior
303              when specifying this flag for regular files and block devices.
304
305              For the handling of FIFOs (named pipes), see also fifo(7).   For
306              a  discussion  of  the  effect of O_NONBLOCK in conjunction with
307              mandatory file locks and with file leases, see fcntl(2).
308
309       O_PATH (since Linux 2.6.39)
310              Obtain a file descriptor that can be used for two  purposes:  to
311              indicate a location in the filesystem tree and to perform opera‐
312              tions that act purely at the file descriptor  level.   The  file
313              itself  is not opened, and other file operations (e.g., read(2),
314              write(2), fchmod(2), fchown(2), fgetxattr(2), ioctl(2), mmap(2))
315              fail with the error EBADF.
316
317              The  following operations can be performed on the resulting file
318              descriptor:
319
320              *  close(2).
321
322              *  fchdir(2), if the  file  descriptor  refers  to  a  directory
323                 (since Linux 3.5).
324
325              *  fstat(2) (since Linux 3.6).
326
327              *  fstatfs(2) (since Linux 3.12).
328
329              *  Duplicating  the  file  descriptor (dup(2), fcntl(2) F_DUPFD,
330                 etc.).
331
332              *  Getting and setting file descriptor flags  (fcntl(2)  F_GETFD
333                 and F_SETFD).
334
335              *  Retrieving  open file status flags using the fcntl(2) F_GETFL
336                 operation: the returned flags will include the bit O_PATH.
337
338              *  Passing the file descriptor as the dirfd argument of openat()
339                 and  the other "*at()" system calls.  This includes linkat(2)
340                 with AT_EMPTY_PATH (or via  procfs  using  AT_SYMLINK_FOLLOW)
341                 even if the file is not a directory.
342
343              *  Passing the file descriptor to another process via a UNIX do‐
344                 main socket (see SCM_RIGHTS in unix(7)).
345
346              When  O_PATH  is  specified  in  flags,  flag  bits  other  than
347              O_CLOEXEC, O_DIRECTORY, and O_NOFOLLOW are ignored.
348
349              Opening  a  file  or  directory with the O_PATH flag requires no
350              permissions on the object itself (but does require execute  per‐
351              mission  on  the  directories in the path prefix).  Depending on
352              the subsequent operation, a check for suitable file  permissions
353              may be performed (e.g., fchdir(2) requires execute permission on
354              the directory referred to by its file descriptor argument).   By
355              contrast,  obtaining a reference to a filesystem object by open‐
356              ing it with the O_RDONLY flag requires that the caller have read
357              permission  on  the  object,  even when the subsequent operation
358              (e.g., fchdir(2), fstat(2)) does not require read permission  on
359              the object.
360
361              If  pathname  is a symbolic link and the O_NOFOLLOW flag is also
362              specified, then the call returns a file descriptor referring  to
363              the  symbolic  link.   This  file  descriptor can be used as the
364              dirfd argument in calls to fchownat(2),  fstatat(2),  linkat(2),
365              and readlinkat(2) with an empty pathname to have the calls oper‐
366              ate on the symbolic link.
367
368              If pathname refers to an automount point that has not  yet  been
369              triggered,  so  no  other  filesystem is mounted on it, then the
370              call returns a file descriptor referring to the automount direc‐
371              tory without triggering a mount.  fstatfs(2) can then be used to
372              determine if it is, in  fact,  an  untriggered  automount  point
373              (.f_type == AUTOFS_SUPER_MAGIC).
374
375              One use of O_PATH for regular files is to provide the equivalent
376              of POSIX.1's O_EXEC functionality.  This permits us  to  open  a
377              file  for  which we have execute permission but not read permis‐
378              sion, and then execute that file, with steps something like  the
379              following:
380
381                  char buf[PATH_MAX];
382                  fd = open("some_prog", O_PATH);
383                  snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd);
384                  execl(buf, "some_prog", (char *) NULL);
385
386              An  O_PATH file descriptor can also be passed as the argument of
387              fexecve(3).
388
389       O_SYNC Write operations on the file will complete according to the  re‐
390              quirements  of  synchronized  I/O  file integrity completion (by
391              contrast with the synchronized  I/O  data  integrity  completion
392              provided by O_DSYNC.)
393
394              By  the  time write(2) (or similar) returns, the output data and
395              associated file metadata have been transferred to the underlying
396              hardware  (i.e.,  as though each write(2) was followed by a call
397              to fsync(2)).  See NOTES below.
398
399       O_TMPFILE (since Linux 3.11)
400              Create an unnamed temporary regular file.  The pathname argument
401              specifies  a directory; an unnamed inode will be created in that
402              directory's filesystem.  Anything written to the resulting  file
403              will be lost when the last file descriptor is closed, unless the
404              file is given a name.
405
406              O_TMPFILE must be specified with one of O_RDWR or O_WRONLY  and,
407              optionally,  O_EXCL.  If O_EXCL is not specified, then linkat(2)
408              can be used to link the temporary file into the filesystem, mak‐
409              ing it permanent, using code like the following:
410
411                  char path[PATH_MAX];
412                  fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
413                                          S_IRUSR | S_IWUSR);
414
415                  /* File I/O on 'fd'... */
416
417                  linkat(fd, "", AT_FDCWD, "/path/for/file", AT_EMPTY_PATH);
418
419                  /* If the caller doesn't have the CAP_DAC_READ_SEARCH
420                     capability (needed to use AT_EMPTY_PATH with linkat(2)),
421                     and there is a proc(5) filesystem mounted, then the
422                     linkat(2) call above can be replaced with:
423
424                  snprintf(path, PATH_MAX,  "/proc/self/fd/%d", fd);
425                  linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
426                                          AT_SYMLINK_FOLLOW);
427                  */
428
429              In  this case, the open() mode argument determines the file per‐
430              mission mode, as with O_CREAT.
431
432              Specifying O_EXCL in conjunction with O_TMPFILE prevents a  tem‐
433              porary  file  from being linked into the filesystem in the above
434              manner.  (Note that the meaning of O_EXCL in this case  is  dif‐
435              ferent from the meaning of O_EXCL otherwise.)
436
437              There are two main use cases for O_TMPFILE:
438
439              *  Improved tmpfile(3) functionality: race-free creation of tem‐
440                 porary files that (1) are automatically deleted when  closed;
441                 (2)  can  never be reached via any pathname; (3) are not sub‐
442                 ject to symlink attacks; and (4) do not require the caller to
443                 devise unique names.
444
445              *  Creating  a  file  that is initially invisible, which is then
446                 populated with data and adjusted to have appropriate filesys‐
447                 tem  attributes  (fchown(2),  fchmod(2),  fsetxattr(2), etc.)
448                 before being atomically linked into the filesystem in a fully
449                 formed state (using linkat(2) as described above).
450
451              O_TMPFILE  requires support by the underlying filesystem; only a
452              subset of Linux filesystems provide that support.  In  the  ini‐
453              tial  implementation,  support  was  provided in the ext2, ext3,
454              ext4, UDF, Minix, and  tmpfs  filesystems.   Support  for  other
455              filesystems  has  subsequently been added as follows: XFS (Linux
456              3.15); Btrfs (Linux 3.16); F2FS (Linux 3.16); and  ubifs  (Linux
457              4.9)
458
459       O_TRUNC
460              If  the file already exists and is a regular file and the access
461              mode allows writing (i.e., is O_RDWR or  O_WRONLY)  it  will  be
462              truncated to length 0.  If the file is a FIFO or terminal device
463              file, the O_TRUNC flag is ignored.   Otherwise,  the  effect  of
464              O_TRUNC is unspecified.
465
466   creat()
467       A  call  to creat() is equivalent to calling open() with flags equal to
468       O_CREAT|O_WRONLY|O_TRUNC.
469
470   openat()
471       The openat() system call operates in exactly the same  way  as  open(),
472       except for the differences described here.
473
474       The dirfd argument is used in conjunction with the pathname argument as
475       follows:
476
477       *  If the pathname given in pathname is absolute,  then  dirfd  is  ig‐
478          nored.
479
480       *  If  the pathname given in pathname is relative and dirfd is the spe‐
481          cial value AT_FDCWD, then pathname is interpreted  relative  to  the
482          current working directory of the calling process (like open()).
483
484       *  If  the  pathname  given  in pathname is relative, then it is inter‐
485          preted relative to the directory referred to by the file  descriptor
486          dirfd  (rather than relative to the current working directory of the
487          calling process, as is done by open() for a relative pathname).   In
488          this  case,  dirfd  must  be a directory that was opened for reading
489          (O_RDONLY) or using the O_PATH flag.
490
491       If the pathname given in pathname is relative, and dirfd is not a valid
492       file descriptor, an error (EBADF) results.  (Specifying an invalid file
493       descriptor number in dirfd can be used as a means to ensure that  path‐
494       name is absolute.)
495
496   openat2(2)
497       The  openat2(2) system call is an extension of openat(), and provides a
498       superset of the features of openat().  It is documented separately,  in
499       openat2(2).
500

RETURN VALUE

502       On  success, open(), openat(), and creat() return the new file descrip‐
503       tor (a nonnegative integer).  On error, -1 is returned and errno is set
504       to indicate the error.
505

ERRORS

507       open(), openat(), and creat() can fail with the following errors:
508
509       EACCES The  requested access to the file is not allowed, or search per‐
510              mission is denied for one of the directories in the path  prefix
511              of  pathname,  or the file did not exist yet and write access to
512              the parent directory is not  allowed.   (See  also  path_resolu‐
513              tion(7).)
514
515       EACCES Where   O_CREAT   is  specified,  the  protected_fifos  or  pro‐
516              tected_regular sysctl is enabled, the file already exists and is
517              a  FIFO  or  regular  file, the owner of the file is neither the
518              current user nor the owner of the containing directory, and  the
519              containing  directory  is  both  world-  or  group-writable  and
520              sticky.  For details, see the descriptions of  /proc/sys/fs/pro‐
521              tected_fifos and /proc/sys/fs/protected_regular in proc(5).
522
523       EBADF  (openat())  pathname  is  relative but dirfd is neither AT_FDCWD
524              nor a valid file descriptor.
525
526       EBUSY  O_EXCL was specified in flags and pathname refers to a block de‐
527              vice that is in use by the system (e.g., it is mounted).
528
529       EDQUOT Where  O_CREAT  is  specified,  the file does not exist, and the
530              user's quota of disk blocks or inodes on the filesystem has been
531              exhausted.
532
533       EEXIST pathname already exists and O_CREAT and O_EXCL were used.
534
535       EFAULT pathname points outside your accessible address space.
536
537       EFBIG  See EOVERFLOW.
538
539       EINTR  While  blocked  waiting  to  complete  an  open of a slow device
540              (e.g., a FIFO; see fifo(7)), the call was interrupted by a  sig‐
541              nal handler; see signal(7).
542
543       EINVAL The  filesystem  does  not support the O_DIRECT flag.  See NOTES
544              for more information.
545
546       EINVAL Invalid value in flags.
547
548       EINVAL O_TMPFILE was specified  in  flags,  but  neither  O_WRONLY  nor
549              O_RDWR was specified.
550
551       EINVAL O_CREAT  was  specified in flags and the final component ("base‐
552              name") of the new file's pathname is invalid (e.g., it  contains
553              characters not permitted by the underlying filesystem).
554
555       EINVAL The  final  component ("basename") of pathname is invalid (e.g.,
556              it contains characters not permitted by the underlying  filesys‐
557              tem).
558
559       EISDIR pathname refers to a directory and the access requested involved
560              writing (that is, O_WRONLY or O_RDWR is set).
561
562       EISDIR pathname refers to an existing directory, O_TMPFILE and  one  of
563              O_WRONLY or O_RDWR were specified in flags, but this kernel ver‐
564              sion does not provide the O_TMPFILE functionality.
565
566       ELOOP  Too many symbolic links were encountered in resolving pathname.
567
568       ELOOP  pathname was a symbolic link, and flags specified O_NOFOLLOW but
569              not O_PATH.
570
571       EMFILE The per-process limit on the number of open file descriptors has
572              been reached (see the  description  of  RLIMIT_NOFILE  in  getr‐
573              limit(2)).
574
575       ENAMETOOLONG
576              pathname was too long.
577
578       ENFILE The system-wide limit on the total number of open files has been
579              reached.
580
581       ENODEV pathname refers to a device special file  and  no  corresponding
582              device  exists.   (This is a Linux kernel bug; in this situation
583              ENXIO must be returned.)
584
585       ENOENT O_CREAT is not set and the named file does not exist.
586
587       ENOENT A directory component in pathname does not exist or  is  a  dan‐
588              gling symbolic link.
589
590       ENOENT pathname refers to a nonexistent directory, O_TMPFILE and one of
591              O_WRONLY or O_RDWR were specified in flags, but this kernel ver‐
592              sion does not provide the O_TMPFILE functionality.
593
594       ENOMEM The  named  file is a FIFO, but memory for the FIFO buffer can't
595              be allocated because the per-user hard limit on  memory  alloca‐
596              tion  for  pipes  has  been reached and the caller is not privi‐
597              leged; see pipe(7).
598
599       ENOMEM Insufficient kernel memory was available.
600
601       ENOSPC pathname was to be created but the  device  containing  pathname
602              has no room for the new file.
603
604       ENOTDIR
605              A  component  used as a directory in pathname is not, in fact, a
606              directory, or O_DIRECTORY was specified and pathname was  not  a
607              directory.
608
609       ENOTDIR
610              (openat())  pathname  is a relative pathname and dirfd is a file
611              descriptor referring to a file other than a directory.
612
613       ENXIO  O_NONBLOCK | O_WRONLY is set, the named file is a FIFO,  and  no
614              process has the FIFO open for reading.
615
616       ENXIO  The  file  is  a device special file and no corresponding device
617              exists.
618
619       ENXIO  The file is a UNIX domain socket.
620
621       EOPNOTSUPP
622              The filesystem containing pathname does not support O_TMPFILE.
623
624       EOVERFLOW
625              pathname refers to a regular  file  that  is  too  large  to  be
626              opened.  The usual scenario here is that an application compiled
627              on a 32-bit platform  without  -D_FILE_OFFSET_BITS=64  tried  to
628              open  a  file  whose  size  exceeds  (1<<31)-1  bytes;  see also
629              O_LARGEFILE above.  This is the error specified by  POSIX.1;  in
630              kernels before 2.6.24, Linux gave the error EFBIG for this case.
631
632       EPERM  The  O_NOATIME  flag was specified, but the effective user ID of
633              the caller did not match the owner of the file  and  the  caller
634              was not privileged.
635
636       EPERM  The operation was prevented by a file seal; see fcntl(2).
637
638       EROFS  pathname  refers  to  a file on a read-only filesystem and write
639              access was requested.
640
641       ETXTBSY
642              pathname refers to an executable image which is currently  being
643              executed and write access was requested.
644
645       ETXTBSY
646              pathname  refers  to  a  file that is currently in use as a swap
647              file, and the O_TRUNC flag was specified.
648
649       ETXTBSY
650              pathname refers to a file that is currently being  read  by  the
651              kernel (e.g., for module/firmware loading), and write access was
652              requested.
653
654       EWOULDBLOCK
655              The O_NONBLOCK flag was specified, and an incompatible lease was
656              held on the file (see fcntl(2)).
657

VERSIONS

659       openat() was added to Linux in kernel 2.6.16; library support was added
660       to glibc in version 2.4.
661

CONFORMING TO

663       open(), creat() SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
664
665       openat(): POSIX.1-2008.
666
667       openat2(2) is Linux-specific.
668
669       The O_DIRECT, O_NOATIME, O_PATH, and  O_TMPFILE  flags  are  Linux-spe‐
670       cific.  One must define _GNU_SOURCE to obtain their definitions.
671
672       The  O_CLOEXEC,  O_DIRECTORY, and O_NOFOLLOW flags are not specified in
673       POSIX.1-2001, but are specified in POSIX.1-2008.  Since glibc 2.12, one
674       can  obtain their definitions by defining either _POSIX_C_SOURCE with a
675       value greater than or equal to 200809L or _XOPEN_SOURCE  with  a  value
676       greater  than  or equal to 700.  In glibc 2.11 and earlier, one obtains
677       the definitions by defining _GNU_SOURCE.
678
679       As  noted  in  feature_test_macros(7),  feature  test  macros  such  as
680       _POSIX_C_SOURCE,  _XOPEN_SOURCE, and _GNU_SOURCE must be defined before
681       including any header files.
682

NOTES

684       Under Linux, the O_NONBLOCK flag is sometimes used in cases  where  one
685       wants  to  open  but does not necessarily have the intention to read or
686       write.  For example, this may be used to open a device in order to  get
687       a file descriptor for use with ioctl(2).
688
689       The  (undefined)  effect of O_RDONLY | O_TRUNC varies among implementa‐
690       tions.  On many systems the file is actually truncated.
691
692       Note that open() can open device special files, but creat() cannot cre‐
693       ate them; use mknod(2) instead.
694
695       If  the  file is newly created, its st_atime, st_ctime, st_mtime fields
696       (respectively, time of last access, time of  last  status  change,  and
697       time  of  last  modification; see stat(2)) are set to the current time,
698       and so are the st_ctime and st_mtime fields of  the  parent  directory.
699       Otherwise,  if  the  file  is modified because of the O_TRUNC flag, its
700       st_ctime and st_mtime fields are set to the current time.
701
702       The files in the /proc/[pid]/fd directory show the open  file  descrip‐
703       tors of the process with the PID pid.  The files in the /proc/[pid]/fd‐
704       info directory show even more information about these file descriptors.
705       See proc(5) for further details of both of these directories.
706
707       The  Linux  header file <asm/fcntl.h> doesn't define O_ASYNC; the (BSD-
708       derived) FASYNC synonym is defined instead.
709
710   Open file descriptions
711       The term open file description is the one used by POSIX to refer to the
712       entries  in  the  system-wide  table of open files.  In other contexts,
713       this object is variously also called an "open  file  object",  a  "file
714       handle",  an "open file table entry", or—in kernel-developer parlance—a
715       struct file.
716
717       When a file descriptor is duplicated (using dup(2) or similar), the du‐
718       plicate  refers  to the same open file description as the original file
719       descriptor, and the two file descriptors consequently  share  the  file
720       offset and file status flags.  Such sharing can also occur between pro‐
721       cesses: a child process created via fork(2) inherits duplicates of  its
722       parent's  file descriptors, and those duplicates refer to the same open
723       file descriptions.
724
725       Each open() of a file creates a new open file description; thus,  there
726       may be multiple open file descriptions corresponding to a file inode.
727
728       On  Linux,  one can use the kcmp(2) KCMP_FILE operation to test whether
729       two file descriptors (in the same process  or  in  two  different  pro‐
730       cesses) refer to the same open file description.
731
732   Synchronized I/O
733       The POSIX.1-2008 "synchronized I/O" option specifies different variants
734       of synchronized I/O, and specifies the open()  flags  O_SYNC,  O_DSYNC,
735       and O_RSYNC for controlling the behavior.  Regardless of whether an im‐
736       plementation supports this option, it must at least support the use  of
737       O_SYNC for regular files.
738
739       Linux  implements O_SYNC and O_DSYNC, but not O_RSYNC.  Somewhat incor‐
740       rectly, glibc defines  O_RSYNC  to  have  the  same  value  as  O_SYNC.
741       (O_RSYNC  is  defined  in the Linux header file <asm/fcntl.h> on HP PA-
742       RISC, but it is not used.)
743
744       O_SYNC provides synchronized I/O  file  integrity  completion,  meaning
745       write operations will flush data and all associated metadata to the un‐
746       derlying hardware.  O_DSYNC provides synchronized  I/O  data  integrity
747       completion,  meaning write operations will flush data to the underlying
748       hardware, but will only flush metadata updates that are required to al‐
749       low  a subsequent read operation to complete successfully.  Data integ‐
750       rity completion can reduce the number of disk operations that  are  re‐
751       quired  for  applications that don't need the guarantees of file integ‐
752       rity completion.
753
754       To understand the difference between the two types of completion,  con‐
755       sider two pieces of file metadata: the file last modification timestamp
756       (st_mtime) and the file length.  All write operations will  update  the
757       last  file modification timestamp, but only writes that add data to the
758       end of the file will change the file  length.   The  last  modification
759       timestamp  is  not needed to ensure that a read completes successfully,
760       but the file length is.  Thus, O_DSYNC would only  guarantee  to  flush
761       updates  to  the file length metadata (whereas O_SYNC would also always
762       flush the last modification timestamp metadata).
763
764       Before Linux 2.6.33, Linux implemented only the O_SYNC flag for open().
765       However,  when  that flag was specified, most filesystems actually pro‐
766       vided the equivalent of  synchronized  I/O  data  integrity  completion
767       (i.e., O_SYNC was actually implemented as the equivalent of O_DSYNC).
768
769       Since Linux 2.6.33, proper O_SYNC support is provided.  However, to en‐
770       sure backward binary compatibility, O_DSYNC was defined with  the  same
771       value  as  the historical O_SYNC, and O_SYNC was defined as a new (two-
772       bit) flag value that includes the O_DSYNC  flag  value.   This  ensures
773       that applications compiled against new headers get at least O_DSYNC se‐
774       mantics on pre-2.6.33 kernels.
775
776   C library/kernel differences
777       Since version 2.26, the glibc wrapper function for open()  employs  the
778       openat() system call, rather than the kernel's open() system call.  For
779       certain architectures, this is also true in glibc versions before 2.26.
780
781   NFS
782       There are many infelicities in the protocol underlying  NFS,  affecting
783       amongst others O_SYNC and O_NDELAY.
784
785       On  NFS  filesystems with UID mapping enabled, open() may return a file
786       descriptor but, for example, read(2) requests are denied  with  EACCES.
787       This is because the client performs open() by checking the permissions,
788       but UID mapping is performed by the server  upon  read  and  write  re‐
789       quests.
790
791   FIFOs
792       Opening  the  read or write end of a FIFO blocks until the other end is
793       also opened (by another process or thread).  See  fifo(7)  for  further
794       details.
795
796   File access mode
797       Unlike the other values that can be specified in flags, the access mode
798       values O_RDONLY, O_WRONLY, and O_RDWR do not specify  individual  bits.
799       Rather,  they  define  the low order two bits of flags, and are defined
800       respectively as 0, 1, and 2.  In other words, the combination  O_RDONLY
801       |  O_WRONLY  is  a  logical error, and certainly does not have the same
802       meaning as O_RDWR.
803
804       Linux reserves the special, nonstandard access mode 3  (binary  11)  in
805       flags  to mean: check for read and write permission on the file and re‐
806       turn a file descriptor that can't be used for reading or writing.  This
807       nonstandard  access mode is used by some Linux drivers to return a file
808       descriptor that is to be used only for device-specific ioctl(2)  opera‐
809       tions.
810
811   Rationale for openat() and other directory file descriptor APIs
812       openat()  and  the other system calls and library functions that take a
813       directory file descriptor argument  (i.e.,  execveat(2),  faccessat(2),
814       fanotify_mark(2),  fchmodat(2), fchownat(2), fspick(2), fstatat(2), fu‐
815       timesat(2),  linkat(2),   mkdirat(2),   mknodat(2),   mount_setattr(2),
816       move_mount(2),  name_to_handle_at(2),  open_tree(2),  openat2(2), read‐
817       linkat(2),  renameat(2),  renameat2(2),  statx(2),  symlinkat(2),   un‐
818       linkat(2),  utimensat(2),  mkfifoat(3),  and  scandirat(3)) address two
819       problems with the older interfaces that preceded them.  Here,  the  ex‐
820       planation is in terms of the openat() call, but the rationale is analo‐
821       gous for the other interfaces.
822
823       First, openat() allows an application to  avoid  race  conditions  that
824       could  occur  when using open() to open files in directories other than
825       the current working directory.  These race conditions result  from  the
826       fact  that some component of the directory prefix given to open() could
827       be changed in parallel with the call to open().  Suppose, for  example,
828       that  we  wish  to  create  the  file  dir1/dir2/xxx.dep  if  the  file
829       dir1/dir2/xxx exists.  The problem is that between the existence  check
830       and  the  file-creation  step,  dir1  or  dir2 (which might be symbolic
831       links) could be modified to point to a different location.  Such  races
832       can  be  avoided by opening a file descriptor for the target directory,
833       and then specifying that file descriptor as the dirfd argument of (say)
834       fstatat(2) and openat().  The use of the dirfd file descriptor also has
835       other benefits:
836
837       *  the file descriptor is a stable reference to the directory, even  if
838          the directory is renamed; and
839
840       *  the open file descriptor prevents the underlying filesystem from be‐
841          ing dismounted, just as when a process has a current working  direc‐
842          tory on a filesystem.
843
844       Second,  openat()  allows  the  implementation of a per-thread "current
845       working directory", via file descriptor(s) maintained by  the  applica‐
846       tion.   (This functionality can also be obtained by tricks based on the
847       use of /proc/self/fd/dirfd, but less efficiently.)
848
849       The dirfd argument for these APIs can be obtained by  using  open()  or
850       openat()  to  open  a directory (with either the O_RDONLY or the O_PATH
851       flag).  Alternatively, such a file descriptor can be obtained by apply‐
852       ing dirfd(3) to a directory stream created using opendir(3).
853
854       When these APIs are given a dirfd argument of AT_FDCWD or the specified
855       pathname is absolute, then they handle their pathname argument  in  the
856       same  way  as  the  corresponding  conventional APIs.  However, in this
857       case, several of the APIs have a flags argument that provides access to
858       functionality that is not available with the corresponding conventional
859       APIs.
860
861   O_DIRECT
862       The O_DIRECT flag may impose alignment restrictions on the  length  and
863       address  of  user-space  buffers and the file offset of I/Os.  In Linux
864       alignment restrictions vary by filesystem and kernel version and  might
865       be  absent entirely.  However there is currently no filesystem-indepen‐
866       dent interface for an application to discover these restrictions for  a
867       given  file  or  filesystem.  Some filesystems provide their own inter‐
868       faces for doing so, for example the XFS_IOC_DIOINFO  operation  in  xf‐
869       sctl(3).
870
871       Under  Linux 2.4, transfer sizes, the alignment of the user buffer, and
872       the file offset must all be multiples of the logical block size of  the
873       filesystem.   Since Linux 2.6.0, alignment to the logical block size of
874       the underlying storage (typically 512  bytes)  suffices.   The  logical
875       block  size can be determined using the ioctl(2) BLKSSZGET operation or
876       from the shell using the command:
877
878           blockdev --getss
879
880       O_DIRECT I/Os should never be run concurrently with the fork(2)  system
881       call, if the memory buffer is a private mapping (i.e., any mapping cre‐
882       ated with the mmap(2) MAP_PRIVATE flag; this includes memory  allocated
883       on  the heap and statically allocated buffers).  Any such I/Os, whether
884       submitted via an asynchronous I/O interface or from another  thread  in
885       the  process, should be completed before fork(2) is called.  Failure to
886       do so can result in data corruption and undefined  behavior  in  parent
887       and  child  processes.  This restriction does not apply when the memory
888       buffer for the O_DIRECT I/Os was created using shmat(2) or mmap(2) with
889       the  MAP_SHARED  flag.  Nor does this restriction apply when the memory
890       buffer has been advised as MADV_DONTFORK with madvise(2), ensuring that
891       it will not be available to the child after fork(2).
892
893       The  O_DIRECT  flag  was introduced in SGI IRIX, where it has alignment
894       restrictions similar to those of Linux 2.4.  IRIX has also  a  fcntl(2)
895       call  to  query  appropriate alignments, and sizes.  FreeBSD 4.x intro‐
896       duced a flag of the same name, but without alignment restrictions.
897
898       O_DIRECT support was added under Linux in kernel version 2.4.10.  Older
899       Linux kernels simply ignore this flag.  Some filesystems may not imple‐
900       ment the flag, in which case open() fails with the error EINVAL  if  it
901       is used.
902
903       Applications  should  avoid  mixing O_DIRECT and normal I/O to the same
904       file, and especially to overlapping byte  regions  in  the  same  file.
905       Even when the filesystem correctly handles the coherency issues in this
906       situation, overall I/O throughput is likely to be slower than using ei‐
907       ther mode alone.  Likewise, applications should avoid mixing mmap(2) of
908       files with direct I/O to the same files.
909
910       The behavior of O_DIRECT with NFS will differ from  local  filesystems.
911       Older  kernels,  or kernels configured in certain ways, may not support
912       this combination.  The NFS protocol does not support passing  the  flag
913       to  the  server, so O_DIRECT I/O will bypass the page cache only on the
914       client; the server may still cache the I/O.  The client asks the server
915       to  make  the  I/O synchronous to preserve the synchronous semantics of
916       O_DIRECT.  Some servers will perform poorly under these  circumstances,
917       especially  if the I/O size is small.  Some servers may also be config‐
918       ured to lie to clients about the I/O  having  reached  stable  storage;
919       this  will avoid the performance penalty at some risk to data integrity
920       in the event of server power failure.  The Linux NFS client  places  no
921       alignment restrictions on O_DIRECT I/O.
922
923       In summary, O_DIRECT is a potentially powerful tool that should be used
924       with caution.  It is recommended that applications treat use  of  O_DI‐
925       RECT as a performance option which is disabled by default.
926

BUGS

928       Currently, it is not possible to enable signal-driven I/O by specifying
929       O_ASYNC when calling open(); use fcntl(2) to enable this flag.
930
931       One must check for two different error codes, EISDIR and  ENOENT,  when
932       trying  to  determine whether the kernel supports O_TMPFILE functional‐
933       ity.
934
935       When both O_CREAT and O_DIRECTORY are specified in flags and  the  file
936       specified by pathname does not exist, open() will create a regular file
937       (i.e., O_DIRECTORY is ignored).
938

SEE ALSO

940       chmod(2), chown(2),  close(2),  dup(2),  fcntl(2),  link(2),  lseek(2),
941       mknod(2), mmap(2), mount(2), open_by_handle_at(2), openat2(2), read(2),
942       socket(2), stat(2), umask(2), unlink(2),  write(2),  fopen(3),  acl(5),
943       fifo(7), inode(7), path_resolution(7), symlink(7)
944

COLOPHON

946       This  page  is  part of release 5.13 of the Linux man-pages project.  A
947       description of the project, information about reporting bugs,  and  the
948       latest     version     of     this    page,    can    be    found    at
949       https://www.kernel.org/doc/man-pages/.
950
951
952
953Linux                             2021-08-27                           OPEN(2)
Impressum