]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
fd185f58 MK |
2 | .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. |
3 | .\" and Copyright (C) 2008 Greg Banks | |
7b8ba76c | 4 | .\" and Copyright (C) 2006, 2008, 2013, 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 5 | .\" |
93015253 | 6 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
7 | .\" Permission is granted to make and distribute verbatim copies of this |
8 | .\" manual provided the copyright notice and this permission notice are | |
9 | .\" preserved on all copies. | |
10 | .\" | |
11 | .\" Permission is granted to copy and distribute modified versions of this | |
12 | .\" manual under the conditions for verbatim copying, provided that the | |
13 | .\" entire resulting derived work is distributed under the terms of a | |
14 | .\" permission notice identical to this one. | |
c13182ef | 15 | .\" |
fea681da MK |
16 | .\" Since the Linux kernel and libraries are constantly changing, this |
17 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
18 | .\" responsibility for errors or omissions, or for damages resulting from | |
19 | .\" the use of the information contained herein. The author(s) may not | |
20 | .\" have taken the same level of care in the production of this manual, | |
21 | .\" which is licensed free of charge, as they might when working | |
22 | .\" professionally. | |
c13182ef | 23 | .\" |
fea681da MK |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 26 | .\" %%%LICENSE_END |
fea681da MK |
27 | .\" |
28 | .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> | |
29 | .\" Modified 1994-08-21 by Michael Haardt | |
30 | .\" Modified 1996-04-13 by Andries Brouwer <aeb@cwi.nl> | |
31 | .\" Modified 1996-05-13 by Thomas Koenig | |
32 | .\" Modified 1996-12-20 by Michael Haardt | |
33 | .\" Modified 1999-02-19 by Andries Brouwer <aeb@cwi.nl> | |
34 | .\" Modified 1998-11-28 by Joseph S. Myers <jsm28@hermes.cam.ac.uk> | |
35 | .\" Modified 1999-06-03 by Michael Haardt | |
c11b1abf MK |
36 | .\" Modified 2002-05-07 by Michael Kerrisk <mtk.manpages@gmail.com> |
37 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> | |
1c1e15ed MK |
38 | .\" 2004-12-08, mtk, reordered flags list alphabetically |
39 | .\" 2004-12-08, Martin Pool <mbp@sourcefrog.net> (& mtk), added O_NOATIME | |
fe75ec04 | 40 | .\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits |
447bb15e | 41 | .\" 2008-01-03, mtk, with input from Trond Myklebust |
f4b9d6a5 MK |
42 | .\" <trond.myklebust@fys.uio.no> and Timo Sirainen <tss@iki.fi> |
43 | .\" Rewrite description of O_EXCL. | |
ddc4d339 MK |
44 | .\" 2008-01-11, Greg Banks <gnb@melbourne.sgi.com>: add more detail |
45 | .\" on O_DIRECT. | |
d77eb764 | 46 | .\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode |
fea681da | 47 | .\" |
61b7c1e1 | 48 | .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and |
9f91e36c MK |
49 | .\" O_TTYINIT. Eventually these may need to be documented. --mtk |
50 | .\" | |
67d2c687 | 51 | .TH OPEN 2 2015-05-07 "Linux" "Linux Programmer's Manual" |
fea681da | 52 | .SH NAME |
7b8ba76c | 53 | open, openat, creat \- open and possibly create a file |
fea681da MK |
54 | .SH SYNOPSIS |
55 | .nf | |
56 | .B #include <sys/types.h> | |
57 | .B #include <sys/stat.h> | |
58 | .B #include <fcntl.h> | |
59 | .sp | |
60 | .BI "int open(const char *" pathname ", int " flags ); | |
61 | .BI "int open(const char *" pathname ", int " flags ", mode_t " mode ); | |
5895e7eb | 62 | |
fea681da | 63 | .BI "int creat(const char *" pathname ", mode_t " mode ); |
7b8ba76c MK |
64 | .sp |
65 | .BI "int openat(int " dirfd ", const char *" pathname ", int " flags ); | |
66 | .BI "int openat(int " dirfd ", const char *" pathname ", int " flags \ | |
67 | ", mode_t " mode ); | |
fea681da | 68 | .fi |
7b8ba76c MK |
69 | .sp |
70 | .in -4n | |
71 | Feature Test Macro Requirements for glibc (see | |
72 | .BR feature_test_macros (7)): | |
73 | .in | |
74 | .sp | |
75 | .BR openat (): | |
76 | .PD 0 | |
77 | .ad l | |
78 | .RS 4 | |
79 | .TP 4 | |
80 | Since glibc 2.10: | |
81 | _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L | |
82 | .TP | |
83 | Before glibc 2.10: | |
84 | _ATFILE_SOURCE | |
85 | .RE | |
86 | .ad | |
87 | .PD | |
fea681da | 88 | .SH DESCRIPTION |
e366dbc4 | 89 | Given a |
0daa9e92 | 90 | .I pathname |
e366dbc4 | 91 | for a file, |
1f6ceb40 | 92 | .BR open () |
2fda57bd | 93 | returns a file descriptor, a small, nonnegative integer |
e366dbc4 MK |
94 | for use in subsequent system calls |
95 | .RB ( read "(2), " write "(2), " lseek "(2), " fcntl "(2), etc.)." | |
96 | The file descriptor returned by a successful call will be | |
2c4bff36 | 97 | the lowest-numbered file descriptor not currently open for the process. |
e366dbc4 | 98 | .PP |
fe75ec04 | 99 | By default, the new file descriptor is set to remain open across an |
e366dbc4 | 100 | .BR execve (2) |
1f6ceb40 MK |
101 | (i.e., the |
102 | .B FD_CLOEXEC | |
103 | file descriptor flag described in | |
31d79098 SP |
104 | .BR fcntl (2) |
105 | is initially disabled); the | |
fe75ec04 | 106 | .B O_CLOEXEC |
d6a74b95 | 107 | flag, described below, can be used to change this default. |
1f6ceb40 | 108 | The file offset is set to the beginning of the file (see |
c13182ef | 109 | .BR lseek (2)). |
e366dbc4 MK |
110 | .PP |
111 | A call to | |
112 | .BR open () | |
113 | creates a new | |
114 | .IR "open file description" , | |
115 | an entry in the system-wide table of open files. | |
61b12e2b | 116 | The open file description records the file offset and the file status flags |
20ee63c1 | 117 | (see below). |
61b12e2b | 118 | A file descriptor is a reference to an open file description; |
2c4bff36 MK |
119 | this reference is unaffected if |
120 | .I pathname | |
121 | is subsequently removed or modified to refer to a different file. | |
d20d9d33 | 122 | For further details on open file descriptions, see NOTES. |
e366dbc4 | 123 | .PP |
c4bb193f | 124 | The argument |
fea681da | 125 | .I flags |
e366dbc4 MK |
126 | must include one of the following |
127 | .IR "access modes" : | |
c7992edc | 128 | .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR . |
e366dbc4 MK |
129 | These request opening the file read-only, write-only, or read/write, |
130 | respectively. | |
bfe9ba67 MK |
131 | |
132 | In addition, zero or more file creation flags and file status flags | |
c13182ef | 133 | can be |
fea681da | 134 | .RI bitwise- or 'd |
e366dbc4 | 135 | in |
bfe9ba67 | 136 | .IR flags . |
c13182ef MK |
137 | The |
138 | .I file creation flags | |
139 | are | |
0e40804c | 140 | .BR O_CLOEXEC , |
b072a788 | 141 | .BR O_CREAT , |
0e40804c MK |
142 | .BR O_DIRECTORY , |
143 | .BR O_EXCL , | |
144 | .BR O_NOCTTY , | |
145 | .BR O_NOFOLLOW , | |
f2698a42 | 146 | .BR O_TMPFILE , |
0e40804c MK |
147 | .BR O_TRUNC , |
148 | and | |
149 | .BR O_TTY_INIT . | |
c13182ef MK |
150 | The |
151 | .I file status flags | |
bfe9ba67 | 152 | are all of the remaining flags listed below. |
0e40804c | 153 | .\" SUSv4 divides the flags into: |
93ee8f96 MK |
154 | .\" * Access mode |
155 | .\" * File creation | |
156 | .\" * File status | |
157 | .\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW) | |
158 | .\" though it's not clear what the difference between "other" and | |
0e40804c MK |
159 | .\" "File creation" flags is. I raised an Aardvark to see if this |
160 | .\" can be clarified in SUSv4; 10 Oct 2008. | |
161 | .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67 | |
162 | .\" TC1 (balloted in 2013), resolved this, so that those three constants | |
163 | .\" are also categorized" as file status flags. | |
164 | .\" | |
bfe9ba67 MK |
165 | The distinction between these two groups of flags is that |
166 | the file status flags can be retrieved and (in some cases) | |
566b427d MK |
167 | modified; see |
168 | .BR fcntl (2) | |
169 | for details. | |
170 | ||
bfe9ba67 | 171 | The full list of file creation flags and file status flags is as follows: |
fea681da | 172 | .TP |
1c1e15ed | 173 | .B O_APPEND |
c13182ef MK |
174 | The file is opened in append mode. |
175 | Before each | |
0bfa087b | 176 | .BR write (2), |
1e568304 | 177 | the file offset is positioned at the end of the file, |
1c1e15ed | 178 | as if with |
0bfa087b | 179 | .BR lseek (2). |
1c1e15ed | 180 | .B O_APPEND |
9ee4a2b6 | 181 | may lead to corrupted files on NFS filesystems if more than one process |
c13182ef | 182 | appends data to a file at once. |
a4391429 MK |
183 | .\" For more background, see |
184 | .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946 | |
185 | .\" http://nfs.sourceforge.net/ | |
c13182ef | 186 | This is because NFS does not support |
1c1e15ed MK |
187 | appending to a file, so the client kernel has to simulate it, which |
188 | can't be done without a race condition. | |
189 | .TP | |
190 | .B O_ASYNC | |
b50582eb | 191 | Enable signal-driven I/O: |
8bd58774 MK |
192 | generate a signal |
193 | .RB ( SIGIO | |
194 | by default, but this can be changed via | |
1c1e15ed MK |
195 | .BR fcntl (2)) |
196 | when input or output becomes possible on this file descriptor. | |
33a0ccb2 | 197 | This feature is available only for terminals, pseudoterminals, |
1f6ceb40 MK |
198 | sockets, and (since Linux 2.6) pipes and FIFOs. |
199 | See | |
1c1e15ed MK |
200 | .BR fcntl (2) |
201 | for further details. | |
9bde4908 | 202 | See also BUGS, below. |
fe75ec04 | 203 | .TP |
31c1f2b0 | 204 | .BR O_CLOEXEC " (since Linux 2.6.23)" |
7fdec065 | 205 | .\" NOTE! several other man pages refer to this text |
fe75ec04 | 206 | Enable the close-on-exec flag for the new file descriptor. |
24ec631f | 207 | Specifying this flag permits a program to avoid additional |
fe75ec04 MK |
208 | .BR fcntl (2) |
209 | .B F_SETFD | |
24ec631f | 210 | operations to set the |
0daa9e92 | 211 | .B FD_CLOEXEC |
fe75ec04 | 212 | flag. |
7756d157 MK |
213 | |
214 | Note that the use of this flag is essential in some multithreaded programs, | |
215 | because using a separate | |
fe75ec04 MK |
216 | .BR fcntl (2) |
217 | .B F_SETFD | |
218 | operation to set the | |
0daa9e92 | 219 | .B FD_CLOEXEC |
fe75ec04 | 220 | flag does not suffice to avoid race conditions |
7756d157 MK |
221 | where one thread opens a file descriptor and |
222 | attempts to set its close-on-exec flag using | |
223 | .BR fcntl (2) | |
224 | at the same time as another thread does a | |
fe75ec04 MK |
225 | .BR fork (2) |
226 | plus | |
227 | .BR execve (2). | |
7756d157 | 228 | Depending on the order of execution, |
30821db8 | 229 | the race may lead to the file descriptor returned by |
7756d157 MK |
230 | .BR open () |
231 | being unintentionally leaked to the program executed by the child process | |
232 | created by | |
233 | .BR fork (2). | |
234 | (This kind of race is in principle possible for any system call | |
235 | that creates a file descriptor whose close-on-exec flag should be set, | |
236 | and various other Linux system calls provide an equivalent of the | |
237 | .BR O_CLOEXEC | |
238 | flag to deal with this problem.) | |
fe75ec04 MK |
239 | .\" This flag fixes only one form of the race condition; |
240 | .\" The race can also occur with, for example, descriptors | |
241 | .\" returned by accept(), pipe(), etc. | |
1c1e15ed | 242 | .TP |
fea681da | 243 | .B O_CREAT |
f1ad56a6 | 244 | If the file does not exist, it will be created. |
fea681da | 245 | The owner (user ID) of the file is set to the effective user ID |
c13182ef MK |
246 | of the process. |
247 | The group ownership (group ID) is set either to | |
fea681da | 248 | the effective group ID of the process or to the group ID of the |
9ee4a2b6 | 249 | parent directory (depending on filesystem type and mount options, |
0fb83d00 | 250 | and the mode of the parent directory; see the mount options |
fea681da MK |
251 | .I bsdgroups |
252 | and | |
253 | .I sysvgroups | |
8b39ad66 | 254 | described in |
fea681da | 255 | .BR mount (8)). |
8b39ad66 MK |
256 | .\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and |
257 | .\" XFS (since 2.6.14). | |
4e698277 MK |
258 | .RS |
259 | .PP | |
260 | .I mode | |
58222012 | 261 | specifies the mode to use in case a new file is created. |
4e698277 MK |
262 | This argument must be supplied when |
263 | .B O_CREAT | |
f2698a42 AL |
264 | or |
265 | .B O_TMPFILE | |
4e698277 MK |
266 | is specified in |
267 | .IR flags ; | |
f2698a42 | 268 | if neither |
4e698277 | 269 | .B O_CREAT |
f2698a42 AL |
270 | nor |
271 | .B O_TMPFILE | |
272 | is specified, then | |
4e698277 MK |
273 | .I mode |
274 | is ignored. | |
58222012 | 275 | The effective mode is modified by the process's |
4e698277 | 276 | .I umask |
58222012 MK |
277 | in the usual way: in the absence of a default ACL, the mode of the |
278 | created file is | |
84a275c4 | 279 | .IR "(mode\ &\ ~umask)" . |
33a0ccb2 | 280 | Note that this mode applies only to future accesses of the |
4e698277 MK |
281 | newly created file; the |
282 | .BR open () | |
283 | call that creates a read-only file may well return a read/write | |
284 | file descriptor. | |
285 | .PP | |
286 | The following symbolic constants are provided for | |
287 | .IR mode : | |
288 | .TP 9 | |
289 | .B S_IRWXU | |
97d5b762 | 290 | 00700 user (file owner) has read, write, and execute permission |
4e698277 MK |
291 | .TP |
292 | .B S_IRUSR | |
293 | 00400 user has read permission | |
294 | .TP | |
295 | .B S_IWUSR | |
296 | 00200 user has write permission | |
297 | .TP | |
298 | .B S_IXUSR | |
299 | 00100 user has execute permission | |
300 | .TP | |
301 | .B S_IRWXG | |
97d5b762 | 302 | 00070 group has read, write, and execute permission |
4e698277 MK |
303 | .TP |
304 | .B S_IRGRP | |
305 | 00040 group has read permission | |
306 | .TP | |
307 | .B S_IWGRP | |
308 | 00020 group has write permission | |
309 | .TP | |
310 | .B S_IXGRP | |
311 | 00010 group has execute permission | |
312 | .TP | |
313 | .B S_IRWXO | |
97d5b762 | 314 | 00007 others have read, write, and execute permission |
4e698277 MK |
315 | .TP |
316 | .B S_IROTH | |
317 | 00004 others have read permission | |
318 | .TP | |
319 | .B S_IWOTH | |
320 | 00002 others have write permission | |
321 | .TP | |
322 | .B S_IXOTH | |
323 | 00001 others have execute permission | |
324 | .RE | |
9e1d8950 MK |
325 | .IP |
326 | According to POSIX, the effect when other bits are set in | |
327 | .I mode | |
328 | is unspecified. | |
329 | On Linux, the following bits are also honored in | |
330 | .IR mode : | |
331 | .RS | |
332 | .TP 9 | |
333 | .B S_ISUID | |
334 | 0004000 set-user-ID bit | |
335 | .TP | |
336 | .B S_ISGID | |
337 | 0002000 set-group-ID bit (see | |
338 | .BR stat (2)) | |
339 | .TP | |
340 | .B S_ISVTX | |
341 | 0001000 sticky bit (see | |
342 | .BR stat (2)) | |
343 | .RE | |
fea681da | 344 | .TP |
31c1f2b0 | 345 | .BR O_DIRECT " (since Linux 2.4.10)" |
1c1e15ed MK |
346 | Try to minimize cache effects of the I/O to and from this file. |
347 | In general this will degrade performance, but it is useful in | |
348 | special situations, such as when applications do their own caching. | |
bce0482f | 349 | File I/O is done directly to/from user-space buffers. |
015221ef CH |
350 | The |
351 | .B O_DIRECT | |
0deb3ce9 | 352 | flag on its own makes an effort to transfer data synchronously, |
015221ef CH |
353 | but does not give the guarantees of the |
354 | .B O_SYNC | |
0deb3ce9 JM |
355 | flag that data and necessary metadata are transferred. |
356 | To guarantee synchronous I/O, | |
015221ef CH |
357 | .B O_SYNC |
358 | must be used in addition to | |
359 | .BR O_DIRECT . | |
be02e49f | 360 | See NOTES below for further discussion. |
9b54d4fa | 361 | .sp |
c13182ef | 362 | A semantically similar (but deprecated) interface for block devices |
9b54d4fa | 363 | is described in |
1c1e15ed MK |
364 | .BR raw (8). |
365 | .TP | |
366 | .B O_DIRECTORY | |
a8d55537 | 367 | If \fIpathname\fP is not a directory, cause the open to fail. |
9f8d688a MK |
368 | .\" But see the following and its replies: |
369 | .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2 | |
370 | .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail | |
371 | .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored. | |
65496644 | 372 | This flag was added in kernel version 2.1.126, to |
60a90ecd MK |
373 | avoid denial-of-service problems if |
374 | .BR opendir (3) | |
375 | is called on a | |
a3041a58 | 376 | FIFO or tape device. |
1c1e15ed | 377 | .TP |
6cf19e62 MK |
378 | .B O_DSYNC |
379 | Write operations on the file will complete according to the requirements of | |
380 | synchronized I/O | |
381 | .I data | |
382 | integrity completion. | |
383 | ||
384 | By the time | |
385 | .BR write (2) | |
386 | (and similar) | |
387 | return, the output data | |
388 | has been transferred to the underlying hardware, | |
389 | along with any file metadata that would be required to retrieve that data | |
390 | (i.e., as though each | |
391 | .BR write (2) | |
392 | was followed by a call to | |
393 | .BR fdatasync (2)). | |
394 | .IR "See NOTES below" . | |
395 | .TP | |
fea681da | 396 | .B O_EXCL |
f4b9d6a5 MK |
397 | Ensure that this call creates the file: |
398 | if this flag is specified in conjunction with | |
fea681da | 399 | .BR O_CREAT , |
f4b9d6a5 MK |
400 | and |
401 | .I pathname | |
402 | already exists, then | |
1c1e15ed | 403 | .BR open () |
c13182ef | 404 | will fail. |
f4b9d6a5 MK |
405 | |
406 | When these two flags are specified, symbolic links are not followed: | |
407 | .\" POSIX.1-2001 explicitly requires this behavior. | |
408 | if | |
409 | .I pathname | |
410 | is a symbolic link, then | |
411 | .BR open () | |
412 | fails regardless of where the symbolic link points to. | |
413 | ||
10b7a945 IHV |
414 | In general, the behavior of |
415 | .B O_EXCL | |
416 | is undefined if it is used without | |
417 | .BR O_CREAT . | |
418 | There is one exception: on Linux 2.6 and later, | |
419 | .B O_EXCL | |
420 | can be used without | |
421 | .B O_CREAT | |
422 | if | |
423 | .I pathname | |
424 | refers to a block device. | |
6303d401 DB |
425 | If the block device is in use by the system (e.g., mounted), |
426 | .BR open () | |
10b7a945 IHV |
427 | fails with the error |
428 | .BR EBUSY . | |
429 | ||
efe08656 | 430 | On NFS, |
f4b9d6a5 | 431 | .B O_EXCL |
33a0ccb2 | 432 | is supported only when using NFSv3 or later on kernel 2.6 or later. |
efe08656 | 433 | In NFS environments where |
fea681da | 434 | .B O_EXCL |
f4b9d6a5 MK |
435 | support is not provided, programs that rely on it |
436 | for performing locking tasks will contain a race condition. | |
437 | Portable programs that want to perform atomic file locking using a lockfile, | |
438 | and need to avoid reliance on NFS support for | |
439 | .BR O_EXCL , | |
440 | can create a unique file on | |
9ee4a2b6 | 441 | the same filesystem (e.g., incorporating hostname and PID), and use |
fea681da | 442 | .BR link (2) |
c13182ef | 443 | to make a link to the lockfile. |
60a90ecd MK |
444 | If |
445 | .BR link (2) | |
f4b9d6a5 | 446 | returns 0, the lock is successful. |
c13182ef | 447 | Otherwise, use |
fea681da MK |
448 | .BR stat (2) |
449 | on the unique file to check if its link count has increased to 2, | |
450 | in which case the lock is also successful. | |
451 | .TP | |
1c1e15ed MK |
452 | .B O_LARGEFILE |
453 | (LFS) | |
454 | Allow files whose sizes cannot be represented in an | |
8478ee02 | 455 | .I off_t |
1c1e15ed | 456 | (but can be represented in an |
8478ee02 | 457 | .IR off64_t ) |
1c1e15ed | 458 | to be opened. |
c13182ef | 459 | The |
bcdd964e | 460 | .B _LARGEFILE64_SOURCE |
e417acb0 MK |
461 | macro must be defined |
462 | (before including | |
463 | .I any | |
464 | header files) | |
465 | in order to obtain this definition. | |
c13182ef | 466 | Setting the |
bcdd964e | 467 | .B _FILE_OFFSET_BITS |
9f3d8b28 MK |
468 | feature test macro to 64 (rather than using |
469 | .BR O_LARGEFILE ) | |
12e263f1 | 470 | is the preferred |
9f3d8b28 | 471 | method of accessing large files on 32-bit systems (see |
2dcbf4f7 | 472 | .BR feature_test_macros (7)). |
1c1e15ed | 473 | .TP |
31c1f2b0 | 474 | .BR O_NOATIME " (since Linux 2.6.8)" |
1bb72c96 MK |
475 | Do not update the file last access time |
476 | .RI ( st_atime | |
477 | in the inode) | |
310b7919 | 478 | when the file is |
1c1e15ed MK |
479 | .BR read (2). |
480 | This flag is intended for use by indexing or backup programs, | |
481 | where its use can significantly reduce the amount of disk activity. | |
9ee4a2b6 | 482 | This flag may not be effective on all filesystems. |
1c1e15ed | 483 | One example is NFS, where the server maintains the access time. |
0e1ad98c | 484 | .\" The O_NOATIME flag also affects the treatment of st_atime |
92057f4d | 485 | .\" by mmap() and readdir(2), MTK, Dec 04. |
1c1e15ed | 486 | .TP |
fea681da MK |
487 | .B O_NOCTTY |
488 | If | |
489 | .I pathname | |
5503c85e | 490 | refers to a terminal device\(emsee |
1bb72c96 MK |
491 | .BR tty (4)\(emit |
492 | will not become the process's controlling terminal even if the | |
fea681da MK |
493 | process does not have one. |
494 | .TP | |
1c1e15ed | 495 | .B O_NOFOLLOW |
a8d55537 | 496 | If \fIpathname\fP is a symbolic link, then the open fails. |
c13182ef | 497 | This is a FreeBSD extension, which was added to Linux in version 2.1.126. |
1c1e15ed | 498 | Symbolic links in earlier components of the pathname will still be |
e366dbc4 | 499 | followed. |
1135dbe1 | 500 | See also |
843068bd | 501 | .BR O_PATH |
1135dbe1 | 502 | below. |
e366dbc4 MK |
503 | .\" The headers from glibc 2.0.100 and later include a |
504 | .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if | |
a8d55537 | 505 | .\" used\fP. |
fea681da MK |
506 | .TP |
507 | .BR O_NONBLOCK " or " O_NDELAY | |
ff40dbb3 | 508 | When possible, the file is opened in nonblocking mode. |
c13182ef | 509 | Neither the |
1c1e15ed | 510 | .BR open () |
fea681da MK |
511 | nor any subsequent operations on the file descriptor which is |
512 | returned will cause the calling process to wait. | |
403b78f8 | 513 | |
9f629381 MK |
514 | Note that this flag has no effect for regular files and block devices; |
515 | that is, I/O operations will (briefly) block when device activity | |
516 | is required, regardless of whether | |
517 | .B O_NONBLOCK | |
518 | is set. | |
519 | Since | |
520 | .B O_NONBLOCK | |
521 | semantics might eventually be implemented, | |
522 | applications should not depend upon blocking behavior | |
523 | when specifying this flag for regular files and block devices. | |
524 | ||
fea681da | 525 | For the handling of FIFOs (named pipes), see also |
af5b2ef2 | 526 | .BR fifo (7). |
db28bfac | 527 | For a discussion of the effect of |
0daa9e92 | 528 | .B O_NONBLOCK |
db28bfac MK |
529 | in conjunction with mandatory file locks and with file leases, see |
530 | .BR fcntl (2). | |
fea681da | 531 | .TP |
1135dbe1 MK |
532 | .BR O_PATH " (since Linux 2.6.39)" |
533 | .\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd | |
534 | .\" commit 326be7b484843988afe57566b627fb7a70beac56 | |
535 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
536 | .\" | |
537 | .\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496 | |
538 | .\" Subject: Re: [PATCH] open(2): document O_PATH | |
539 | .\" Newsgroups: gmane.linux.man, gmane.linux.kernel | |
540 | .\" | |
1135dbe1 | 541 | Obtain a file descriptor that can be used for two purposes: |
9ee4a2b6 | 542 | to indicate a location in the filesystem tree and |
1135dbe1 MK |
543 | to perform operations that act purely at the file descriptor level. |
544 | The file itself is not opened, and other file operations (e.g., | |
545 | .BR read (2), | |
546 | .BR write (2), | |
547 | .BR fchmod (2), | |
548 | .BR fchown (2), | |
2510e4e5 RH |
549 | .BR fgetxattr (2), |
550 | .BR mmap (2)) | |
1135dbe1 MK |
551 | fail with the error |
552 | .BR EBADF . | |
553 | ||
554 | The following operations | |
555 | .I can | |
556 | be performed on the resulting file descriptor: | |
557 | .RS | |
558 | .IP * 3 | |
559 | .BR close (2); | |
560 | .BR fchdir (2) | |
561 | (since Linux 3.5); | |
562 | .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24 | |
563 | .BR fstat (2) | |
564 | (since Linux 3.6). | |
565 | .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2 | |
566 | .IP * | |
567 | Duplicating the file descriptor | |
568 | .RB ( dup (2), | |
569 | .BR fcntl (2) | |
570 | .BR F_DUPFD , | |
571 | etc.). | |
572 | .IP * | |
573 | Getting and setting file descriptor flags | |
574 | .RB ( fcntl (2) | |
575 | .BR F_GETFD | |
576 | and | |
577 | .BR F_SETFD ). | |
09f677a3 MK |
578 | .IP * |
579 | Retrieving open file status flags using the | |
580 | .BR fcntl (2) | |
13a082cb | 581 | .BR F_GETFL |
09f677a3 MK |
582 | operation: the returned flags will include the bit |
583 | .BR O_PATH . | |
1135dbe1 MK |
584 | .IP * |
585 | Passing the file descriptor as the | |
586 | .IR dirfd | |
587 | argument of | |
588 | .BR openat (2) | |
589 | and the other "*at()" system calls. | |
7dee406b AL |
590 | This includes |
591 | .BR linkat (2) | |
592 | with | |
0da5e58a | 593 | .BR AT_EMPTY_PATH |
7dee406b AL |
594 | (or via procfs using |
595 | .BR AT_SYMLINK_FOLLOW ) | |
596 | even if the file is not a directory. | |
1135dbe1 MK |
597 | .IP * |
598 | Passing the file descriptor to another process via a UNIX domain socket | |
599 | (see | |
600 | .BR SCM_RIGHTS | |
601 | in | |
602 | .BR unix (7)). | |
603 | .RE | |
604 | .IP | |
605 | When | |
606 | .B O_PATH | |
607 | is specified in | |
608 | .IR flags , | |
609 | flag bits other than | |
6807fc6f MK |
610 | .BR O_CLOEXEC , |
611 | .BR O_DIRECTORY , | |
1135dbe1 MK |
612 | and |
613 | .BR O_NOFOLLOW | |
614 | are ignored. | |
615 | ||
d30344ab MK |
616 | If |
617 | .I pathname | |
618 | is a symbolic link and the | |
1135dbe1 MK |
619 | .BR O_NOFOLLOW |
620 | flag is also specified, | |
621 | then the call returns a file descriptor referring to the symbolic link. | |
622 | This file descriptor can be used as the | |
623 | .I dirfd | |
624 | argument in calls to | |
625 | .BR fchownat (2), | |
626 | .BR fstatat (2), | |
627 | .BR linkat (2), | |
628 | and | |
629 | .BR readlinkat (2) | |
630 | with an empty pathname to have the calls operate on the symbolic link. | |
631 | .TP | |
fea681da | 632 | .B O_SYNC |
6cf19e62 MK |
633 | Write operations on the file will complete according to the requirements of |
634 | synchronized I/O | |
635 | .I file | |
636 | integrity completion | |
f36a1468 | 637 | (by contrast with the |
6cf19e62 MK |
638 | synchronized I/O |
639 | .I data | |
640 | integrity completion | |
641 | provided by | |
642 | .BR O_DSYNC .) | |
643 | ||
644 | By the time | |
645 | .BR write (2) | |
646 | (and similar) | |
647 | return, the output data and associated file metadata | |
648 | have been transferred to the underlying hardware | |
649 | (i.e., as though each | |
650 | .BR write (2) | |
651 | was followed by a call to | |
652 | .BR fsync (2)). | |
653 | .IR "See NOTES below" . | |
fea681da | 654 | .TP |
40398c1a MK |
655 | .BR O_TMPFILE " (since Linux 3.11)" |
656 | .\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e | |
657 | .\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e | |
658 | .\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd | |
659 | Create an unnamed temporary file. | |
660 | The | |
661 | .I pathname | |
662 | argument specifies a directory; | |
663 | an unnamed inode will be created in that directory's filesystem. | |
664 | Anything written to the resulting file will be lost when | |
665 | the last file descriptor is closed, unless the file is given a name. | |
666 | ||
667 | .B O_TMPFILE | |
668 | must be specified with one of | |
669 | .B O_RDWR | |
670 | or | |
671 | .B O_WRONLY | |
672 | and, optionally, | |
673 | .BR O_EXCL . | |
674 | If | |
675 | .B O_EXCL | |
676 | is not specified, then | |
677 | .BR linkat (2) | |
678 | can be used to link the temporary file into the filesystem, making it | |
679 | permanent, using code like the following: | |
680 | ||
681 | .in +4n | |
682 | .nf | |
683 | char path[PATH_MAX]; | |
684 | fd = open("/path/to/dir", O_TMPFILE | O_RDWR, | |
0fb83d00 MK |
685 | S_IRUSR | S_IWUSR); |
686 | ||
40398c1a | 687 | /* File I/O on 'fd'... */ |
0fb83d00 | 688 | |
40398c1a | 689 | snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd); |
e1252130 | 690 | linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file", |
0fb83d00 | 691 | AT_SYMLINK_FOLLOW); |
40398c1a MK |
692 | .fi |
693 | .in | |
694 | ||
695 | In this case, | |
696 | the | |
697 | .BR open () | |
698 | .I mode | |
699 | argument determines the file permission mode, as with | |
700 | .BR O_CREAT . | |
701 | ||
0115aaed MK |
702 | Specifying |
703 | .B O_EXCL | |
704 | in conjunction with | |
705 | .B O_TMPFILE | |
706 | prevents a temporary file from being linked into the filesystem | |
707 | in the above manner. | |
708 | (Note that the meaning of | |
709 | .B O_EXCL | |
710 | in this case is different from the meaning of | |
711 | .B O_EXCL | |
712 | otherwise.) | |
713 | ||
714 | ||
40398c1a MK |
715 | There are two main use cases for |
716 | .\" Inspired by http://lwn.net/Articles/559147/ | |
717 | .BR O_TMPFILE : | |
718 | .RS | |
719 | .IP * 3 | |
720 | Improved | |
721 | .BR tmpfile (3) | |
722 | functionality: race-free creation of temporary files that | |
723 | (1) are automatically deleted when closed; | |
724 | (2) can never be reached via any pathname; | |
725 | (3) are not subject to symlink attacks; and | |
726 | (4) do not require the caller to devise unique names. | |
727 | .IP * | |
728 | Creating a file that is initially invisible, which is then populated | |
8b04592d | 729 | with data and adjusted to have appropriate filesystem attributes |
40398c1a MK |
730 | .RB ( chown (2), |
731 | .BR chmod (2), | |
732 | .BR fsetxattr (2), | |
733 | etc.) | |
734 | before being atomically linked into the filesystem | |
735 | in a fully formed state (using | |
736 | .BR linkat (2) | |
737 | as described above). | |
738 | .RE | |
739 | .IP | |
740 | .B O_TMPFILE | |
741 | requires support by the underlying filesystem; | |
40398c1a | 742 | only a subset of Linux filesystems provide that support. |
cde2074a | 743 | In the initial implementation, support was provided in |
9af6b115 | 744 | the ext2, ext3, ext4, UDF, Minix, and shmem filesystems. |
cde2074a MK |
745 | XFS support was added |
746 | .\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788 | |
747 | .\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe | |
748 | in Linux 3.15. | |
40398c1a | 749 | .TP |
1c1e15ed | 750 | .B O_TRUNC |
4d61d36a | 751 | If the file already exists and is a regular file and the access mode allows |
682edefb MK |
752 | writing (i.e., is |
753 | .B O_RDWR | |
754 | or | |
755 | .BR O_WRONLY ) | |
756 | it will be truncated to length 0. | |
757 | If the file is a FIFO or terminal device file, the | |
758 | .B O_TRUNC | |
c13182ef | 759 | flag is ignored. |
2b9b829d | 760 | Otherwise, the effect of |
682edefb MK |
761 | .B O_TRUNC |
762 | is unspecified. | |
7b8ba76c | 763 | .SS creat() |
1c1e15ed | 764 | .BR creat () |
fea681da | 765 | is equivalent to |
1c1e15ed | 766 | .BR open () |
fea681da MK |
767 | with |
768 | .I flags | |
769 | equal to | |
770 | .BR O_CREAT|O_WRONLY|O_TRUNC . | |
7b8ba76c MK |
771 | .SS openat() |
772 | The | |
773 | .BR openat () | |
774 | system call operates in exactly the same way as | |
cadd38ba | 775 | .BR open (), |
7b8ba76c MK |
776 | except for the differences described here. |
777 | ||
778 | If the pathname given in | |
779 | .I pathname | |
780 | is relative, then it is interpreted relative to the directory | |
3ad65ff0 | 781 | referred to by the file descriptor |
7b8ba76c MK |
782 | .I dirfd |
783 | (rather than relative to the current working directory of | |
784 | the calling process, as is done by | |
cadd38ba | 785 | .BR open () |
7b8ba76c MK |
786 | for a relative pathname). |
787 | ||
788 | If | |
789 | .I pathname | |
790 | is relative and | |
791 | .I dirfd | |
792 | is the special value | |
793 | .BR AT_FDCWD , | |
794 | then | |
795 | .I pathname | |
796 | is interpreted relative to the current working | |
797 | directory of the calling process (like | |
cadd38ba | 798 | .BR open ()). |
7b8ba76c MK |
799 | |
800 | If | |
801 | .I pathname | |
802 | is absolute, then | |
803 | .I dirfd | |
804 | is ignored. | |
47297adb | 805 | .SH RETURN VALUE |
7b8ba76c MK |
806 | .BR open (), |
807 | .BR openat (), | |
c13182ef | 808 | and |
e1d6264d | 809 | .BR creat () |
1c1e15ed MK |
810 | return the new file descriptor, or \-1 if an error occurred |
811 | (in which case, | |
fea681da MK |
812 | .I errno |
813 | is set appropriately). | |
fea681da | 814 | .SH ERRORS |
7b8ba76c MK |
815 | .BR open (), |
816 | .BR openat (), | |
817 | and | |
818 | .BR creat () | |
819 | can fail with the following errors: | |
fea681da MK |
820 | .TP |
821 | .B EACCES | |
822 | The requested access to the file is not allowed, or search permission | |
823 | is denied for one of the directories in the path prefix of | |
824 | .IR pathname , | |
825 | or the file did not exist yet and write access to the parent directory | |
826 | is not allowed. | |
827 | (See also | |
ad7cc990 | 828 | .BR path_resolution (7).) |
fea681da | 829 | .TP |
a1f01685 MH |
830 | .B EDQUOT |
831 | Where | |
832 | .B O_CREAT | |
833 | is specified, the file does not exist, and the user's quota of disk | |
9ee4a2b6 | 834 | blocks or inodes on the filesystem has been exhausted. |
a1f01685 | 835 | .TP |
fea681da MK |
836 | .B EEXIST |
837 | .I pathname | |
838 | already exists and | |
839 | .BR O_CREAT " and " O_EXCL | |
840 | were used. | |
841 | .TP | |
842 | .B EFAULT | |
0daa9e92 | 843 | .I pathname |
e1d6264d | 844 | points outside your accessible address space. |
fea681da | 845 | .TP |
9f5773f7 | 846 | .B EFBIG |
7c7fb552 MK |
847 | See |
848 | .BR EOVERFLOW . | |
9f5773f7 | 849 | .TP |
e51412ea MK |
850 | .B EINTR |
851 | While blocked waiting to complete an open of a slow device | |
852 | (e.g., a FIFO; see | |
853 | .BR fifo (7)), | |
854 | the call was interrupted by a signal handler; see | |
855 | .BR signal (7). | |
856 | .TP | |
ef490193 DG |
857 | .B EINVAL |
858 | The filesystem does not support the | |
859 | .BR O_DIRECT | |
e6f89ed2 MK |
860 | flag. |
861 | See | |
ef490193 DG |
862 | .BR NOTES |
863 | for more information. | |
864 | .TP | |
8e335391 MK |
865 | .B EINVAL |
866 | Invalid value in | |
867 | .\" In particular, __O_TMPFILE instead of O_TMPFILE | |
868 | .IR flags . | |
869 | .TP | |
870 | .B EINVAL | |
871 | .B O_TMPFILE | |
872 | was specified in | |
873 | .IR flags , | |
874 | but neither | |
875 | .B O_WRONLY | |
876 | nor | |
877 | .B O_RDWR | |
878 | was specified. | |
879 | .TP | |
fea681da MK |
880 | .B EISDIR |
881 | .I pathname | |
882 | refers to a directory and the access requested involved writing | |
883 | (that is, | |
884 | .B O_WRONLY | |
885 | or | |
886 | .B O_RDWR | |
887 | is set). | |
888 | .TP | |
8e335391 | 889 | .B EISDIR |
843068bd MK |
890 | .I pathname |
891 | refers to an existing directory, | |
8e335391 MK |
892 | .B O_TMPFILE |
893 | and one of | |
894 | .B O_WRONLY | |
895 | or | |
896 | .B O_RDWR | |
897 | were specified in | |
898 | .IR flags , | |
899 | but this kernel version does not provide the | |
900 | .B O_TMPFILE | |
901 | functionality. | |
902 | .TP | |
fea681da MK |
903 | .B ELOOP |
904 | Too many symbolic links were encountered in resolving | |
289f7907 MK |
905 | .IR pathname . |
906 | .TP | |
907 | .B ELOOP | |
fea681da | 908 | .I pathname |
289f7907 MK |
909 | was a symbolic link, and |
910 | .I flags | |
911 | specified | |
912 | .BR O_NOFOLLOW | |
913 | but not | |
914 | .BR O_PATH . | |
fea681da MK |
915 | .TP |
916 | .B EMFILE | |
12c21590 MK |
917 | The process already has the maximum number of files open |
918 | (see the description of | |
919 | .BR RLIMIT_NOFILE | |
920 | in | |
921 | .BR getrlimit (2)). | |
fea681da MK |
922 | .TP |
923 | .B ENAMETOOLONG | |
0daa9e92 | 924 | .I pathname |
e1d6264d | 925 | was too long. |
fea681da MK |
926 | .TP |
927 | .B ENFILE | |
928 | The system limit on the total number of open files has been reached. | |
929 | .TP | |
930 | .B ENODEV | |
931 | .I pathname | |
932 | refers to a device special file and no corresponding device exists. | |
682edefb MK |
933 | (This is a Linux kernel bug; in this situation |
934 | .B ENXIO | |
935 | must be returned.) | |
fea681da MK |
936 | .TP |
937 | .B ENOENT | |
682edefb MK |
938 | .B O_CREAT |
939 | is not set and the named file does not exist. | |
fea681da MK |
940 | Or, a directory component in |
941 | .I pathname | |
942 | does not exist or is a dangling symbolic link. | |
943 | .TP | |
ba03011f MK |
944 | .B ENOENT |
945 | .I pathname | |
946 | refers to a nonexistent directory, | |
947 | .B O_TMPFILE | |
948 | and one of | |
949 | .B O_WRONLY | |
950 | or | |
951 | .B O_RDWR | |
952 | were specified in | |
953 | .IR flags , | |
954 | but this kernel version does not provide the | |
955 | .B O_TMPFILE | |
956 | functionality. | |
957 | .TP | |
fea681da MK |
958 | .B ENOMEM |
959 | Insufficient kernel memory was available. | |
960 | .TP | |
961 | .B ENOSPC | |
962 | .I pathname | |
963 | was to be created but the device containing | |
964 | .I pathname | |
965 | has no room for the new file. | |
966 | .TP | |
967 | .B ENOTDIR | |
968 | A component used as a directory in | |
969 | .I pathname | |
a8d55537 | 970 | is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and |
fea681da MK |
971 | .I pathname |
972 | was not a directory. | |
973 | .TP | |
974 | .B ENXIO | |
682edefb | 975 | .BR O_NONBLOCK " | " O_WRONLY |
103ea4f6 MK |
976 | is set, the named file is a FIFO, and |
977 | no process has the FIFO open for reading. | |
fea681da MK |
978 | Or, the file is a device special file and no corresponding device exists. |
979 | .TP | |
bbe02b45 MK |
980 | .BR EOPNOTSUPP |
981 | The filesystem containing | |
982 | .I pathname | |
983 | does not support | |
984 | .BR O_TMPFILE . | |
985 | .TP | |
7c7fb552 MK |
986 | .B EOVERFLOW |
987 | .I pathname | |
988 | refers to a regular file that is too large to be opened. | |
989 | The usual scenario here is that an application compiled | |
990 | on a 32-bit platform without | |
5e4dc269 | 991 | .I -D_FILE_OFFSET_BITS=64 |
7c7fb552 | 992 | tried to open a file whose size exceeds |
4e1a4d72 MK |
993 | .I (1<<31)-1 |
994 | bytes; | |
7c7fb552 MK |
995 | see also |
996 | .B O_LARGEFILE | |
997 | above. | |
c84d3aa3 | 998 | This is the error specified by POSIX.1; |
7c7fb552 MK |
999 | in kernels before 2.6.24, Linux gave the error |
1000 | .B EFBIG | |
1001 | for this case. | |
1002 | .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253 | |
1003 | .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW" | |
1004 | .\" Reported 2006-10-03 | |
1005 | .TP | |
1c1e15ed MK |
1006 | .B EPERM |
1007 | The | |
1008 | .B O_NOATIME | |
1009 | flag was specified, but the effective user ID of the caller | |
9ee4a2b6 | 1010 | .\" Strictly speaking, it's the filesystem UID... (MTK) |
1c1e15ed MK |
1011 | did not match the owner of the file and the caller was not privileged |
1012 | .RB ( CAP_FOWNER ). | |
1013 | .TP | |
fbab10e5 MK |
1014 | .B EPERM |
1015 | The operation was prevented by a file seal; see | |
1016 | .BR fcntl (2). | |
1017 | .TP | |
fea681da MK |
1018 | .B EROFS |
1019 | .I pathname | |
9ee4a2b6 | 1020 | refers to a file on a read-only filesystem and write access was |
fea681da MK |
1021 | requested. |
1022 | .TP | |
1023 | .B ETXTBSY | |
1024 | .I pathname | |
1025 | refers to an executable image which is currently being executed and | |
1026 | write access was requested. | |
d3952311 MK |
1027 | .TP |
1028 | .B EWOULDBLOCK | |
1029 | The | |
1030 | .B O_NONBLOCK | |
1031 | flag was specified, and an incompatible lease was held on the file | |
1032 | (see | |
1033 | .BR fcntl (2)). | |
7b8ba76c MK |
1034 | .PP |
1035 | The following additional errors can occur for | |
1036 | .BR openat (): | |
1037 | .TP | |
1038 | .B EBADF | |
1039 | .I dirfd | |
1040 | is not a valid file descriptor. | |
1041 | .TP | |
1042 | .B ENOTDIR | |
1043 | .I pathname | |
2feae602 | 1044 | is a relative pathname and |
7b8ba76c MK |
1045 | .I dirfd |
1046 | is a file descriptor referring to a file other than a directory. | |
1047 | .SH VERSIONS | |
1048 | .BR openat () | |
1049 | was added to Linux in kernel 2.6.16; | |
1050 | library support was added to glibc in version 2.4. | |
47297adb | 1051 | .SH CONFORMING TO |
7b8ba76c MK |
1052 | .BR open (), |
1053 | .BR creat () | |
72ac7268 MK |
1054 | SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. |
1055 | ||
7b8ba76c MK |
1056 | .BR openat (): |
1057 | POSIX.1-2008. | |
7b8ba76c | 1058 | |
fea681da | 1059 | The |
72ac7268 | 1060 | .BR O_DIRECT , |
1c1e15ed | 1061 | .BR O_NOATIME , |
72ac7268 | 1062 | .BR O_PATH , |
fea681da | 1063 | and |
72ac7268 MK |
1064 | .BR O_TMPFILE |
1065 | flags are Linux-specific. | |
1066 | One must define | |
61b7c1e1 MK |
1067 | .B _GNU_SOURCE |
1068 | to obtain their definitions. | |
9f91e36c MK |
1069 | |
1070 | The | |
72ac7268 MK |
1071 | .BR O_CLOEXEC , |
1072 | .BR O_DIRECTORY , | |
1073 | and | |
1074 | .BR O_NOFOLLOW | |
1075 | flags are not specified in POSIX.1-2001, | |
1076 | but are specified in POSIX.1-2008. | |
1077 | Since glibc 2.12, one can obtain their definitions by defining either | |
1078 | .B _POSIX_C_SOURCE | |
1079 | with a value greater than or equal to 200809L or | |
1080 | .BR _XOPEN_SOURCE | |
1081 | with a value greater than or equal to 700. | |
1082 | In glibc 2.11 and earlier, one obtains the definitions by defining | |
1083 | .BR _GNU_SOURCE . | |
9f91e36c | 1084 | |
72ac7268 MK |
1085 | As noted in |
1086 | .BR feature_test_macros (7), | |
84fc2a6e | 1087 | feature test macros such as |
72ac7268 MK |
1088 | .BR _POSIX_C_SOURCE , |
1089 | .BR _XOPEN_SOURCE , | |
1090 | and | |
fe75ec04 | 1091 | .B _GNU_SOURCE |
72ac7268 | 1092 | must be defined before including |
e417acb0 | 1093 | .I any |
72ac7268 | 1094 | header files. |
a1d5f77c | 1095 | .SH NOTES |
988db661 | 1096 | Under Linux, the |
a1d5f77c MK |
1097 | .B O_NONBLOCK |
1098 | flag indicates that one wants to open | |
1099 | but does not necessarily have the intention to read or write. | |
1100 | This is typically used to open devices in order to get a file descriptor | |
1101 | for use with | |
1102 | .BR ioctl (2). | |
c734b9f2 | 1103 | |
fea681da MK |
1104 | .LP |
1105 | The (undefined) effect of | |
1106 | .B O_RDONLY | O_TRUNC | |
c13182ef | 1107 | varies among implementations. |
bcdd964e | 1108 | On many systems the file is actually truncated. |
fea681da MK |
1109 | .\" Linux 2.0, 2.5: truncate |
1110 | .\" Solaris 5.7, 5.8: truncate | |
1111 | .\" Irix 6.5: truncate | |
1112 | .\" Tru64 5.1B: truncate | |
1113 | .\" HP-UX 11.22: truncate | |
1114 | .\" FreeBSD 4.7: truncate | |
a1d5f77c | 1115 | |
5dc8986d MK |
1116 | Note that |
1117 | .BR open () | |
1118 | can open device special files, but | |
1119 | .BR creat () | |
1120 | cannot create them; use | |
1121 | .BR mknod (2) | |
1122 | instead. | |
1123 | ||
1124 | If the file is newly created, its | |
1125 | .IR st_atime , | |
1126 | .IR st_ctime , | |
1127 | .I st_mtime | |
1128 | fields | |
1129 | (respectively, time of last access, time of last status change, and | |
1130 | time of last modification; see | |
1131 | .BR stat (2)) | |
1132 | are set | |
1133 | to the current time, and so are the | |
1134 | .I st_ctime | |
1135 | and | |
1136 | .I st_mtime | |
1137 | fields of the | |
1138 | parent directory. | |
1139 | Otherwise, if the file is modified because of the | |
1140 | .B O_TRUNC | |
3a9c5a29 MK |
1141 | flag, its |
1142 | .I st_ctime | |
1143 | and | |
1144 | .I st_mtime | |
1145 | fields are set to the current time. | |
5dc8986d MK |
1146 | .\" |
1147 | .\" | |
d20d9d33 MK |
1148 | .SS Open file descriptions |
1149 | The term open file description is the one used by POSIX to refer to the | |
1150 | entries in the system-wide table of open files. | |
91085d85 | 1151 | In other contexts, this object is |
d20d9d33 MK |
1152 | variously also called an "open file object", |
1153 | a "file handle", an "open file table entry", | |
1154 | or\(emin kernel-developer parlance\(ema | |
1155 | .IR "struct file" . | |
1156 | ||
1157 | When a file descriptor is duplicated (using | |
1158 | .BR dup (2) | |
1159 | or similar), | |
1160 | the duplicate refers to the same open file description | |
1161 | as the original file descriptor, | |
1162 | and the two file descriptors consequently share | |
1163 | the file offset and file status flags. | |
1164 | Such sharing can also occur between processes: | |
1165 | a child process created via | |
91085d85 | 1166 | .BR fork (2) |
d20d9d33 MK |
1167 | inherits duplicates of its parent's file descriptors, |
1168 | and those duplicates refer to the same open file descriptions. | |
1169 | ||
1170 | Each | |
1171 | .BR open (2) | |
1172 | of a file creates a new open file description; | |
1173 | thus, there may be multiple open file descriptions | |
1174 | corresponding to a file inode. | |
1175 | .\" | |
1176 | .\" | |
5dc8986d | 1177 | .SS Synchronized I/O |
6cf19e62 MK |
1178 | The POSIX.1-2008 "synchronized I/O" option |
1179 | specifies different variants of synchronized I/O, | |
1180 | and specifies the | |
1181 | .BR open () | |
1182 | flags | |
015221ef CH |
1183 | .BR O_SYNC , |
1184 | .BR O_DSYNC , | |
1185 | and | |
6cf19e62 MK |
1186 | .BR O_RSYNC |
1187 | for controlling the behavior. | |
1188 | Regardless of whether an implementation supports this option, | |
1189 | it must at least support the use of | |
1190 | .BR O_SYNC | |
1191 | for regular files. | |
1192 | ||
89851a00 | 1193 | Linux implements |
6cf19e62 MK |
1194 | .BR O_SYNC |
1195 | and | |
1196 | .BR O_DSYNC , | |
1197 | but not | |
015221ef | 1198 | .BR O_RSYNC . |
6cf19e62 MK |
1199 | (Somewhat incorrectly, glibc defines |
1200 | .BR O_RSYNC | |
1201 | to have the same value as | |
1202 | .BR O_SYNC .) | |
1203 | ||
1204 | .BR O_SYNC | |
1205 | provides synchronized I/O | |
1206 | .I file | |
1207 | integrity completion, | |
1208 | meaning write operations will flush data and all associated metadata | |
1209 | to the underlying hardware. | |
1210 | .BR O_DSYNC | |
1211 | provides synchronized I/O | |
1212 | .I data | |
1213 | integrity completion, | |
1214 | meaning write operations will flush data | |
1215 | to the underlying hardware, | |
1216 | but will only flush metadata updates that are required | |
1217 | to allow a subsequent read operation to complete successfully. | |
1218 | Data integrity completion can reduce the number of disk operations | |
1219 | that are required for applications that don't need the guarantees | |
1220 | of file integrity completion. | |
1221 | ||
a83923ca | 1222 | To understand the difference between the two types of completion, |
6cf19e62 MK |
1223 | consider two pieces of file metadata: |
1224 | the file last modification timestamp | |
1225 | .RI ( st_mtime ) | |
1226 | and the file length. | |
1227 | All write operations will update the last file modification timestamp, | |
1228 | but only writes that add data to the end of the | |
1229 | file will change the file length. | |
1230 | The last modification timestamp is not needed to ensure that | |
1231 | a read completes successfully, but the file length is. | |
1232 | Thus, | |
1233 | .BR O_DSYNC | |
1234 | would only guarantee to flush updates to the file length metadata | |
1235 | (whereas | |
1236 | .BR O_SYNC | |
1237 | would also always flush the last modification timestamp metadata). | |
1238 | ||
1239 | Before Linux 2.6.33, Linux implemented only the | |
1240 | .BR O_SYNC | |
89851a00 | 1241 | flag for |
6cf19e62 MK |
1242 | .BR open (). |
1243 | However, when that flag was specified, | |
1244 | most filesystems actually provided the equivalent of synchronized I/O | |
1245 | .I data | |
1246 | integrity completion (i.e., | |
1247 | .BR O_SYNC | |
1248 | was actually implemented as the equivalent of | |
1249 | .BR O_DSYNC ). | |
1250 | ||
1251 | Since Linux 2.6.33, proper | |
1252 | .BR O_SYNC | |
1253 | support is provided. | |
1254 | However, to ensure backward binary compatibility, | |
1255 | .BR O_DSYNC | |
1256 | was defined with the same value as the historical | |
015221ef | 1257 | .BR O_SYNC , |
015221ef | 1258 | and |
6cf19e62 | 1259 | .BR O_SYNC |
89851a00 | 1260 | was defined as a new (two-bit) flag value that includes the |
6cf19e62 MK |
1261 | .BR O_DSYNC |
1262 | flag value. | |
1263 | This ensures that applications compiled against | |
1264 | new headers get at least | |
1265 | .BR O_DSYNC | |
1266 | semantics on pre-2.6.33 kernels. | |
5dc8986d MK |
1267 | .\" |
1268 | .\" | |
1269 | .SS NFS | |
1270 | There are many infelicities in the protocol underlying NFS, affecting | |
1271 | amongst others | |
1272 | .BR O_SYNC " and " O_NDELAY . | |
a1d5f77c | 1273 | |
9ee4a2b6 | 1274 | On NFS filesystems with UID mapping enabled, |
a1d5f77c MK |
1275 | .BR open () |
1276 | may | |
75b94dc3 | 1277 | return a file descriptor but, for example, |
a1d5f77c MK |
1278 | .BR read (2) |
1279 | requests are denied | |
1280 | with \fBEACCES\fP. | |
1281 | This is because the client performs | |
1282 | .BR open () | |
1283 | by checking the | |
1284 | permissions, but UID mapping is performed by the server upon | |
1285 | read and write requests. | |
5dc8986d MK |
1286 | .\" |
1287 | .\" | |
1bdc161d MK |
1288 | .SS FIFOs |
1289 | Opening the read or write end of a FIFO blocks until the other | |
1290 | end is also opened (by another process or thread). | |
1291 | See | |
1292 | .BR fifo (7) | |
1293 | for further details. | |
1294 | .\" | |
1295 | .\" | |
5dc8986d MK |
1296 | .SS File access mode |
1297 | Unlike the other values that can be specified in | |
1298 | .IR flags , | |
1299 | the | |
1300 | .I "access mode" | |
1301 | values | |
1302 | .BR O_RDONLY ", " O_WRONLY ", and " O_RDWR | |
1303 | do not specify individual bits. | |
1304 | Rather, they define the low order two bits of | |
1305 | .IR flags , | |
1306 | and are defined respectively as 0, 1, and 2. | |
1307 | In other words, the combination | |
1308 | .B "O_RDONLY | O_WRONLY" | |
1309 | is a logical error, and certainly does not have the same meaning as | |
1310 | .BR O_RDWR . | |
a1d5f77c | 1311 | |
5dc8986d MK |
1312 | Linux reserves the special, nonstandard access mode 3 (binary 11) in |
1313 | .I flags | |
1314 | to mean: | |
1315 | check for read and write permission on the file and return a descriptor | |
1316 | that can't be used for reading or writing. | |
1317 | This nonstandard access mode is used by some Linux drivers to return a | |
1318 | descriptor that is to be used only for device-specific | |
1319 | .BR ioctl (2) | |
1320 | operations. | |
1321 | .\" See for example util-linux's disk-utils/setfdprm.c | |
1322 | .\" For some background on access mode 3, see | |
1323 | .\" http://thread.gmane.org/gmane.linux.kernel/653123 | |
1324 | .\" "[RFC] correct flags to f_mode conversion in __dentry_open" | |
1325 | .\" LKML, 12 Mar 2008 | |
7b8ba76c MK |
1326 | .\" |
1327 | .\" | |
80d250b4 | 1328 | .SS Rationale for openat() and other "directory file descriptor" APIs |
7b8ba76c | 1329 | .BR openat () |
80d250b4 MK |
1330 | and the other system calls and library functions that take |
1331 | a directory file descriptor argument | |
7b8ba76c | 1332 | (i.e., |
c6a16783 | 1333 | .BR execveat (2), |
7b8ba76c | 1334 | .BR faccessat (2), |
80d250b4 | 1335 | .BR fanotify_mark (2), |
7b8ba76c MK |
1336 | .BR fchmodat (2), |
1337 | .BR fchownat (2), | |
1338 | .BR fstatat (2), | |
1339 | .BR futimesat (2), | |
1340 | .BR linkat (2), | |
1341 | .BR mkdirat (2), | |
1342 | .BR mknodat (2), | |
80d250b4 | 1343 | .BR name_to_handle_at (2), |
7b8ba76c MK |
1344 | .BR readlinkat (2), |
1345 | .BR renameat (2), | |
1346 | .BR symlinkat (2), | |
1347 | .BR unlinkat (2), | |
f37759b1 | 1348 | .BR utimensat (2), |
80d250b4 | 1349 | .BR mkfifoat (3), |
7b8ba76c | 1350 | and |
80d250b4 | 1351 | .BR scandirat (3)) |
7b8ba76c MK |
1352 | are supported |
1353 | for two reasons. | |
92692952 | 1354 | Here, the explanation is in terms of the |
7b8ba76c | 1355 | .BR openat () |
d26f8a31 | 1356 | call, but the rationale is analogous for the other interfaces. |
7b8ba76c MK |
1357 | |
1358 | First, | |
1359 | .BR openat () | |
1360 | allows an application to avoid race conditions that could | |
1361 | occur when using | |
cadd38ba | 1362 | .BR open () |
7b8ba76c MK |
1363 | to open files in directories other than the current working directory. |
1364 | These race conditions result from the fact that some component | |
1365 | of the directory prefix given to | |
cadd38ba | 1366 | .BR open () |
7b8ba76c | 1367 | could be changed in parallel with the call to |
cadd38ba | 1368 | .BR open (). |
54305f5b MK |
1369 | Suppose, for example, that we wish to create the file |
1370 | .I path/to/xxx.dep | |
1371 | if the file | |
1372 | .I path/to/xxx | |
1373 | exists. | |
1374 | The problem is that between the existence check and the file creation step, | |
1375 | .I path | |
1376 | or | |
1377 | .I to | |
1378 | (which might be symbolic links) | |
1379 | could be modified to point to a different location. | |
7b8ba76c MK |
1380 | Such races can be avoided by |
1381 | opening a file descriptor for the target directory, | |
1382 | and then specifying that file descriptor as the | |
1383 | .I dirfd | |
54305f5b MK |
1384 | argument of (say) |
1385 | .BR fstatat (2) | |
1386 | and | |
7b8ba76c MK |
1387 | .BR openat (). |
1388 | ||
1389 | Second, | |
1390 | .BR openat () | |
1391 | allows the implementation of a per-thread "current working | |
1392 | directory", via file descriptor(s) maintained by the application. | |
1393 | (This functionality can also be obtained by tricks based | |
1394 | on the use of | |
1395 | .IR /proc/self/fd/ dirfd, | |
1396 | but less efficiently.) | |
1397 | .\" | |
1398 | .\" | |
ddc4d339 MK |
1399 | .SS O_DIRECT |
1400 | .LP | |
1401 | The | |
1402 | .B O_DIRECT | |
1403 | flag may impose alignment restrictions on the length and address | |
7fac88a9 | 1404 | of user-space buffers and the file offset of I/Os. |
ddc4d339 | 1405 | In Linux alignment |
9ee4a2b6 | 1406 | restrictions vary by filesystem and kernel version and might be |
ddc4d339 | 1407 | absent entirely. |
9ee4a2b6 | 1408 | However there is currently no filesystem\-independent |
ddc4d339 | 1409 | interface for an application to discover these restrictions for a given |
9ee4a2b6 MK |
1410 | file or filesystem. |
1411 | Some filesystems provide their own interfaces | |
ddc4d339 MK |
1412 | for doing so, for example the |
1413 | .B XFS_IOC_DIOINFO | |
1414 | operation in | |
1415 | .BR xfsctl (3). | |
1416 | .LP | |
85c2bdba MK |
1417 | Under Linux 2.4, transfer sizes, and the alignment of the user buffer |
1418 | and the file offset must all be multiples of the logical block size | |
9ee4a2b6 | 1419 | of the filesystem. |
21557928 | 1420 | Since Linux 2.6.0, alignment to the logical block size of the |
e6042e4a | 1421 | underlying storage (typically 512 bytes) suffices. |
21557928 | 1422 | The logical block size can be determined using the |
e6042e4a PS |
1423 | .BR ioctl (2) |
1424 | .B BLKSSZGET | |
21557928 MK |
1425 | operation or from the shell using the command: |
1426 | ||
1427 | blockdev \-\-getss | |
1847167b NP |
1428 | .LP |
1429 | .B O_DIRECT | |
1430 | I/Os should never be run concurrently with the | |
04cd7f64 | 1431 | .BR fork (2) |
1847167b NP |
1432 | system call, |
1433 | if the memory buffer is a private mapping | |
1434 | (i.e., any mapping created with the | |
02ace852 | 1435 | .BR mmap (2) |
1847167b | 1436 | .BR MAP_PRIVATE |
0ab8aeec | 1437 | flag; |
1847167b NP |
1438 | this includes memory allocated on the heap and statically allocated buffers). |
1439 | Any such I/Os, whether submitted via an asynchronous I/O interface or from | |
1440 | another thread in the process, | |
1441 | should be completed before | |
1442 | .BR fork (2) | |
1443 | is called. | |
1444 | Failure to do so can result in data corruption and undefined behavior in | |
1445 | parent and child processes. | |
1446 | This restriction does not apply when the memory buffer for the | |
1447 | .B O_DIRECT | |
1448 | I/Os was created using | |
1449 | .BR shmat (2) | |
1450 | or | |
1451 | .BR mmap (2) | |
1452 | with the | |
1453 | .B MAP_SHARED | |
1454 | flag. | |
1455 | Nor does this restriction apply when the memory buffer has been advised as | |
1456 | .B MADV_DONTFORK | |
0ab8aeec | 1457 | with |
02ace852 | 1458 | .BR madvise (2), |
1847167b NP |
1459 | ensuring that it will not be available |
1460 | to the child after | |
1461 | .BR fork (2). | |
ddc4d339 MK |
1462 | .LP |
1463 | The | |
1464 | .B O_DIRECT | |
1465 | flag was introduced in SGI IRIX, where it has alignment | |
1466 | restrictions similar to those of Linux 2.4. | |
1467 | IRIX has also a | |
1468 | .BR fcntl (2) | |
1469 | call to query appropriate alignments, and sizes. | |
1470 | FreeBSD 4.x introduced | |
1471 | a flag of the same name, but without alignment restrictions. | |
1472 | .LP | |
1473 | .B O_DIRECT | |
1474 | support was added under Linux in kernel version 2.4.10. | |
1475 | Older Linux kernels simply ignore this flag. | |
9ee4a2b6 | 1476 | Some filesystems may not implement the flag and |
ddc4d339 MK |
1477 | .BR open () |
1478 | will fail with | |
1479 | .B EINVAL | |
1480 | if it is used. | |
1481 | .LP | |
1482 | Applications should avoid mixing | |
1483 | .B O_DIRECT | |
1484 | and normal I/O to the same file, | |
1485 | and especially to overlapping byte regions in the same file. | |
9ee4a2b6 | 1486 | Even when the filesystem correctly handles the coherency issues in |
ddc4d339 MK |
1487 | this situation, overall I/O throughput is likely to be slower than |
1488 | using either mode alone. | |
1489 | Likewise, applications should avoid mixing | |
1490 | .BR mmap (2) | |
1491 | of files with direct I/O to the same files. | |
1492 | .LP | |
a1fa36af | 1493 | The behavior of |
ddc4d339 | 1494 | .B O_DIRECT |
9ee4a2b6 | 1495 | with NFS will differ from local filesystems. |
ddc4d339 MK |
1496 | Older kernels, or |
1497 | kernels configured in certain ways, may not support this combination. | |
1498 | The NFS protocol does not support passing the flag to the server, so | |
1499 | .B O_DIRECT | |
33a0ccb2 | 1500 | I/O will bypass the page cache only on the client; the server may |
ddc4d339 MK |
1501 | still cache the I/O. |
1502 | The client asks the server to make the I/O | |
1503 | synchronous to preserve the synchronous semantics of | |
1504 | .BR O_DIRECT . | |
1505 | Some servers will perform poorly under these circumstances, especially | |
1506 | if the I/O size is small. | |
1507 | Some servers may also be configured to | |
1508 | lie to clients about the I/O having reached stable storage; this | |
1509 | will avoid the performance penalty at some risk to data integrity | |
1510 | in the event of server power failure. | |
1511 | The Linux NFS client places no alignment restrictions on | |
1512 | .B O_DIRECT | |
1513 | I/O. | |
1514 | .PP | |
1515 | In summary, | |
1516 | .B O_DIRECT | |
1517 | is a potentially powerful tool that should be used with caution. | |
1518 | It is recommended that applications treat use of | |
1519 | .B O_DIRECT | |
1520 | as a performance option which is disabled by default. | |
1521 | .PP | |
1522 | .RS | |
fea681da MK |
1523 | "The thing that has always disturbed me about O_DIRECT is that the whole |
1524 | interface is just stupid, and was probably designed by a deranged monkey | |
5503c85e | 1525 | on some serious mind-controlling substances."\(emLinus |
ddc4d339 MK |
1526 | .RE |
1527 | .SH BUGS | |
b50582eb MK |
1528 | Currently, it is not possible to enable signal-driven |
1529 | I/O by specifying | |
1530 | .B O_ASYNC | |
c13182ef | 1531 | when calling |
b50582eb MK |
1532 | .BR open (); |
1533 | use | |
1534 | .BR fcntl (2) | |
1535 | to enable this flag. | |
0e1ad98c | 1536 | .\" FIXME . Check bugzilla report on open(O_ASYNC) |
92057f4d | 1537 | .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 |
0d730fcc MK |
1538 | |
1539 | One must check for two different error codes, | |
1540 | .B EISDIR | |
1541 | and | |
1542 | .BR ENOENT , | |
1543 | when trying to determine whether the kernel supports | |
0d55b37f | 1544 | .B O_TMPFILE |
0d730fcc | 1545 | functionality. |
320f8a8e MK |
1546 | |
1547 | When both | |
1548 | .B O_CREAT | |
1549 | and | |
1550 | .B O_DIRECTORY | |
1551 | are specified in | |
1552 | .IR flags | |
1553 | and the file specified by | |
1554 | .I pathname | |
1555 | does not exist, | |
1556 | .BR open () | |
1557 | will create a regular file (i.e., | |
1558 | .B O_DIRECTORY | |
1559 | is ignored). | |
47297adb | 1560 | .SH SEE ALSO |
a3bf8022 MK |
1561 | .BR chmod (2), |
1562 | .BR chown (2), | |
fea681da | 1563 | .BR close (2), |
e366dbc4 | 1564 | .BR dup (2), |
fea681da MK |
1565 | .BR fcntl (2), |
1566 | .BR link (2), | |
1f6ceb40 | 1567 | .BR lseek (2), |
fea681da | 1568 | .BR mknod (2), |
e366dbc4 | 1569 | .BR mmap (2), |
f0c34053 | 1570 | .BR mount (2), |
fa5d243f | 1571 | .BR open_by_handle_at (2), |
fea681da MK |
1572 | .BR read (2), |
1573 | .BR socket (2), | |
1574 | .BR stat (2), | |
1575 | .BR umask (2), | |
1576 | .BR unlink (2), | |
1577 | .BR write (2), | |
1578 | .BR fopen (3), | |
a57c98a0 | 1579 | .BR acl (5) |
f0c34053 | 1580 | .BR fifo (7), |
a9cfde1d MK |
1581 | .BR path_resolution (7), |
1582 | .BR symlink (7) |