]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
ac56b6a8 MK |
2 | .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. |
3 | .\" and Copyright (C) 2008 Greg Banks | |
fea681da | 4 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
fea681da MK |
26 | .\" |
27 | .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> | |
28 | .\" Modified 1994-08-21 by Michael Haardt | |
29 | .\" Modified 1996-04-13 by Andries Brouwer <aeb@cwi.nl> | |
30 | .\" Modified 1996-05-13 by Thomas Koenig | |
31 | .\" Modified 1996-12-20 by Michael Haardt | |
32 | .\" Modified 1999-02-19 by Andries Brouwer <aeb@cwi.nl> | |
33 | .\" Modified 1998-11-28 by Joseph S. Myers <jsm28@hermes.cam.ac.uk> | |
34 | .\" Modified 1999-06-03 by Michael Haardt | |
c11b1abf MK |
35 | .\" Modified 2002-05-07 by Michael Kerrisk <mtk.manpages@gmail.com> |
36 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> | |
1c1e15ed MK |
37 | .\" 2004-12-08, mtk, reordered flags list alphabetically |
38 | .\" 2004-12-08, Martin Pool <mbp@sourcefrog.net> (& mtk), added O_NOATIME | |
fe75ec04 | 39 | .\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits |
447bb15e | 40 | .\" 2008-01-03, mtk, with input from Trond Myklebust |
f4b9d6a5 MK |
41 | .\" <trond.myklebust@fys.uio.no> and Timo Sirainen <tss@iki.fi> |
42 | .\" Rewrite description of O_EXCL. | |
ddc4d339 MK |
43 | .\" 2008-01-11, Greg Banks <gnb@melbourne.sgi.com>: add more detail |
44 | .\" on O_DIRECT. | |
d77eb764 | 45 | .\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode |
fea681da | 46 | .\" |
61b7c1e1 | 47 | .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and |
9f91e36c | 48 | .\" O_TTYINIT. Eventually these may need to be documented. --mtk |
803e1d2f | 49 | .\" FIXME Linux 2.6.33 has O_DSYNC, and a hidden __O_SYNC. |
9f91e36c | 50 | .\" |
a3041a58 | 51 | .TH OPEN 2 2013-07-21 "Linux" "Linux Programmer's Manual" |
fea681da MK |
52 | .SH NAME |
53 | open, creat \- open and possibly create a file or device | |
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 MK |
63 | .BI "int creat(const char *" pathname ", mode_t " mode ); |
64 | .fi | |
65 | .SH DESCRIPTION | |
e366dbc4 | 66 | Given a |
0daa9e92 | 67 | .I pathname |
e366dbc4 | 68 | for a file, |
1f6ceb40 | 69 | .BR open () |
2fda57bd | 70 | returns a file descriptor, a small, nonnegative integer |
e366dbc4 MK |
71 | for use in subsequent system calls |
72 | .RB ( read "(2), " write "(2), " lseek "(2), " fcntl "(2), etc.)." | |
73 | The file descriptor returned by a successful call will be | |
2c4bff36 | 74 | the lowest-numbered file descriptor not currently open for the process. |
e366dbc4 | 75 | .PP |
fe75ec04 | 76 | By default, the new file descriptor is set to remain open across an |
e366dbc4 | 77 | .BR execve (2) |
1f6ceb40 MK |
78 | (i.e., the |
79 | .B FD_CLOEXEC | |
80 | file descriptor flag described in | |
81 | .BR fcntl (2) | |
fd3ac440 | 82 | is initially disabled; the |
fe75ec04 MK |
83 | .B O_CLOEXEC |
84 | flag, described below, can be used to change this default). | |
1f6ceb40 | 85 | The file offset is set to the beginning of the file (see |
c13182ef | 86 | .BR lseek (2)). |
e366dbc4 MK |
87 | .PP |
88 | A call to | |
89 | .BR open () | |
90 | creates a new | |
91 | .IR "open file description" , | |
92 | an entry in the system-wide table of open files. | |
e366dbc4 MK |
93 | This entry records the file offset and the file status flags |
94 | (modifiable via the | |
0bfa087b | 95 | .BR fcntl (2) |
e366dbc4 MK |
96 | .B F_SETFL |
97 | operation). | |
2c4bff36 MK |
98 | A file descriptor is a reference to one of these entries; |
99 | this reference is unaffected if | |
100 | .I pathname | |
101 | is subsequently removed or modified to refer to a different file. | |
e366dbc4 | 102 | The new open file description is initially not shared |
2c4bff36 MK |
103 | with any other process, |
104 | but sharing may arise via | |
105 | .BR fork (2). | |
e366dbc4 | 106 | .PP |
c4bb193f | 107 | The argument |
fea681da | 108 | .I flags |
e366dbc4 MK |
109 | must include one of the following |
110 | .IR "access modes" : | |
c7992edc | 111 | .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR . |
e366dbc4 MK |
112 | These request opening the file read-only, write-only, or read/write, |
113 | respectively. | |
bfe9ba67 MK |
114 | |
115 | In addition, zero or more file creation flags and file status flags | |
c13182ef | 116 | can be |
fea681da | 117 | .RI bitwise- or 'd |
e366dbc4 | 118 | in |
bfe9ba67 | 119 | .IR flags . |
c13182ef MK |
120 | The |
121 | .I file creation flags | |
122 | are | |
0e40804c | 123 | .BR O_CLOEXEC , |
b072a788 | 124 | .BR O_CREAT , |
0e40804c MK |
125 | .BR O_DIRECTORY , |
126 | .BR O_EXCL , | |
127 | .BR O_NOCTTY , | |
128 | .BR O_NOFOLLOW , | |
129 | .BR O_TRUNC , | |
130 | and | |
131 | .BR O_TTY_INIT . | |
c13182ef MK |
132 | The |
133 | .I file status flags | |
bfe9ba67 | 134 | are all of the remaining flags listed below. |
0e40804c | 135 | .\" SUSv4 divides the flags into: |
93ee8f96 MK |
136 | .\" * Access mode |
137 | .\" * File creation | |
138 | .\" * File status | |
139 | .\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW) | |
140 | .\" though it's not clear what the difference between "other" and | |
0e40804c MK |
141 | .\" "File creation" flags is. I raised an Aardvark to see if this |
142 | .\" can be clarified in SUSv4; 10 Oct 2008. | |
143 | .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67 | |
144 | .\" TC1 (balloted in 2013), resolved this, so that those three constants | |
145 | .\" are also categorized" as file status flags. | |
146 | .\" | |
bfe9ba67 MK |
147 | The distinction between these two groups of flags is that |
148 | the file status flags can be retrieved and (in some cases) | |
149 | modified using | |
150 | .BR fcntl (2). | |
151 | The full list of file creation flags and file status flags is as follows: | |
fea681da | 152 | .TP |
1c1e15ed | 153 | .B O_APPEND |
c13182ef MK |
154 | The file is opened in append mode. |
155 | Before each | |
0bfa087b | 156 | .BR write (2), |
1e568304 | 157 | the file offset is positioned at the end of the file, |
1c1e15ed | 158 | as if with |
0bfa087b | 159 | .BR lseek (2). |
1c1e15ed | 160 | .B O_APPEND |
9ee4a2b6 | 161 | may lead to corrupted files on NFS filesystems if more than one process |
c13182ef | 162 | appends data to a file at once. |
a4391429 MK |
163 | .\" For more background, see |
164 | .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946 | |
165 | .\" http://nfs.sourceforge.net/ | |
c13182ef | 166 | This is because NFS does not support |
1c1e15ed MK |
167 | appending to a file, so the client kernel has to simulate it, which |
168 | can't be done without a race condition. | |
169 | .TP | |
170 | .B O_ASYNC | |
b50582eb | 171 | Enable signal-driven I/O: |
8bd58774 MK |
172 | generate a signal |
173 | .RB ( SIGIO | |
174 | by default, but this can be changed via | |
1c1e15ed MK |
175 | .BR fcntl (2)) |
176 | when input or output becomes possible on this file descriptor. | |
33a0ccb2 | 177 | This feature is available only for terminals, pseudoterminals, |
1f6ceb40 MK |
178 | sockets, and (since Linux 2.6) pipes and FIFOs. |
179 | See | |
1c1e15ed MK |
180 | .BR fcntl (2) |
181 | for further details. | |
fe75ec04 MK |
182 | .TP |
183 | .BR O_CLOEXEC " (Since Linux 2.6.23)" | |
184 | Enable the close-on-exec flag for the new file descriptor. | |
24ec631f | 185 | Specifying this flag permits a program to avoid additional |
fe75ec04 MK |
186 | .BR fcntl (2) |
187 | .B F_SETFD | |
24ec631f | 188 | operations to set the |
0daa9e92 | 189 | .B FD_CLOEXEC |
fe75ec04 MK |
190 | flag. |
191 | Additionally, | |
192 | use of this flag is essential in some multithreaded programs | |
193 | since using a separate | |
194 | .BR fcntl (2) | |
195 | .B F_SETFD | |
196 | operation to set the | |
0daa9e92 | 197 | .B FD_CLOEXEC |
fe75ec04 MK |
198 | flag does not suffice to avoid race conditions |
199 | where one thread opens a file descriptor at the same | |
200 | time as another thread does a | |
201 | .BR fork (2) | |
202 | plus | |
203 | .BR execve (2). | |
204 | .\" This flag fixes only one form of the race condition; | |
205 | .\" The race can also occur with, for example, descriptors | |
206 | .\" returned by accept(), pipe(), etc. | |
1c1e15ed | 207 | .TP |
fea681da MK |
208 | .B O_CREAT |
209 | If the file does not exist it will be created. | |
210 | The owner (user ID) of the file is set to the effective user ID | |
c13182ef MK |
211 | of the process. |
212 | The group ownership (group ID) is set either to | |
fea681da | 213 | the effective group ID of the process or to the group ID of the |
9ee4a2b6 | 214 | parent directory (depending on filesystem type and mount options, |
8b39ad66 | 215 | and the mode of the parent directory, see the mount options |
fea681da MK |
216 | .I bsdgroups |
217 | and | |
218 | .I sysvgroups | |
8b39ad66 | 219 | described in |
fea681da | 220 | .BR mount (8)). |
8b39ad66 MK |
221 | .\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and |
222 | .\" XFS (since 2.6.14). | |
4e698277 MK |
223 | .RS |
224 | .PP | |
225 | .I mode | |
226 | specifies the permissions to use in case a new file is created. | |
227 | This argument must be supplied when | |
228 | .B O_CREAT | |
229 | is specified in | |
230 | .IR flags ; | |
231 | if | |
232 | .B O_CREAT | |
233 | is not specified, then | |
234 | .I mode | |
235 | is ignored. | |
236 | The effective permissions are modified by | |
237 | the process's | |
238 | .I umask | |
239 | in the usual way: The permissions of the created file are | |
84a275c4 | 240 | .IR "(mode\ &\ ~umask)" . |
33a0ccb2 | 241 | Note that this mode applies only to future accesses of the |
4e698277 MK |
242 | newly created file; the |
243 | .BR open () | |
244 | call that creates a read-only file may well return a read/write | |
245 | file descriptor. | |
246 | .PP | |
247 | The following symbolic constants are provided for | |
248 | .IR mode : | |
249 | .TP 9 | |
250 | .B S_IRWXU | |
251 | 00700 user (file owner) has read, write and execute permission | |
252 | .TP | |
253 | .B S_IRUSR | |
254 | 00400 user has read permission | |
255 | .TP | |
256 | .B S_IWUSR | |
257 | 00200 user has write permission | |
258 | .TP | |
259 | .B S_IXUSR | |
260 | 00100 user has execute permission | |
261 | .TP | |
262 | .B S_IRWXG | |
263 | 00070 group has read, write and execute permission | |
264 | .TP | |
265 | .B S_IRGRP | |
266 | 00040 group has read permission | |
267 | .TP | |
268 | .B S_IWGRP | |
269 | 00020 group has write permission | |
270 | .TP | |
271 | .B S_IXGRP | |
272 | 00010 group has execute permission | |
273 | .TP | |
274 | .B S_IRWXO | |
275 | 00007 others have read, write and execute permission | |
276 | .TP | |
277 | .B S_IROTH | |
278 | 00004 others have read permission | |
279 | .TP | |
280 | .B S_IWOTH | |
281 | 00002 others have write permission | |
282 | .TP | |
283 | .B S_IXOTH | |
284 | 00001 others have execute permission | |
285 | .RE | |
fea681da | 286 | .TP |
ddc4d339 | 287 | .BR O_DIRECT " (Since Linux 2.4.10)" |
1c1e15ed MK |
288 | Try to minimize cache effects of the I/O to and from this file. |
289 | In general this will degrade performance, but it is useful in | |
290 | special situations, such as when applications do their own caching. | |
bce0482f | 291 | File I/O is done directly to/from user-space buffers. |
015221ef CH |
292 | The |
293 | .B O_DIRECT | |
0deb3ce9 | 294 | flag on its own makes an effort to transfer data synchronously, |
015221ef CH |
295 | but does not give the guarantees of the |
296 | .B O_SYNC | |
0deb3ce9 JM |
297 | flag that data and necessary metadata are transferred. |
298 | To guarantee synchronous I/O, | |
015221ef CH |
299 | .B O_SYNC |
300 | must be used in addition to | |
301 | .BR O_DIRECT . | |
be02e49f | 302 | See NOTES below for further discussion. |
9b54d4fa | 303 | .sp |
c13182ef | 304 | A semantically similar (but deprecated) interface for block devices |
9b54d4fa | 305 | is described in |
1c1e15ed MK |
306 | .BR raw (8). |
307 | .TP | |
308 | .B O_DIRECTORY | |
a8d55537 | 309 | If \fIpathname\fP is not a directory, cause the open to fail. |
9f8d688a MK |
310 | .\" But see the following and its replies: |
311 | .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2 | |
312 | .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail | |
313 | .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored. | |
8382f16d | 314 | This flag is Linux-specific, and was added in kernel version 2.1.126, to |
60a90ecd MK |
315 | avoid denial-of-service problems if |
316 | .BR opendir (3) | |
317 | is called on a | |
a3041a58 | 318 | FIFO or tape device. |
1c1e15ed | 319 | .TP |
fea681da | 320 | .B O_EXCL |
f4b9d6a5 MK |
321 | Ensure that this call creates the file: |
322 | if this flag is specified in conjunction with | |
fea681da | 323 | .BR O_CREAT , |
f4b9d6a5 MK |
324 | and |
325 | .I pathname | |
326 | already exists, then | |
1c1e15ed | 327 | .BR open () |
c13182ef | 328 | will fail. |
f4b9d6a5 MK |
329 | |
330 | When these two flags are specified, symbolic links are not followed: | |
331 | .\" POSIX.1-2001 explicitly requires this behavior. | |
332 | if | |
333 | .I pathname | |
334 | is a symbolic link, then | |
335 | .BR open () | |
336 | fails regardless of where the symbolic link points to. | |
337 | ||
10b7a945 IHV |
338 | In general, the behavior of |
339 | .B O_EXCL | |
340 | is undefined if it is used without | |
341 | .BR O_CREAT . | |
342 | There is one exception: on Linux 2.6 and later, | |
343 | .B O_EXCL | |
344 | can be used without | |
345 | .B O_CREAT | |
346 | if | |
347 | .I pathname | |
348 | refers to a block device. | |
6303d401 DB |
349 | If the block device is in use by the system (e.g., mounted), |
350 | .BR open () | |
10b7a945 IHV |
351 | fails with the error |
352 | .BR EBUSY . | |
353 | ||
efe08656 | 354 | On NFS, |
f4b9d6a5 | 355 | .B O_EXCL |
33a0ccb2 | 356 | is supported only when using NFSv3 or later on kernel 2.6 or later. |
efe08656 | 357 | In NFS environments where |
fea681da | 358 | .B O_EXCL |
f4b9d6a5 MK |
359 | support is not provided, programs that rely on it |
360 | for performing locking tasks will contain a race condition. | |
361 | Portable programs that want to perform atomic file locking using a lockfile, | |
362 | and need to avoid reliance on NFS support for | |
363 | .BR O_EXCL , | |
364 | can create a unique file on | |
9ee4a2b6 | 365 | the same filesystem (e.g., incorporating hostname and PID), and use |
fea681da | 366 | .BR link (2) |
c13182ef | 367 | to make a link to the lockfile. |
60a90ecd MK |
368 | If |
369 | .BR link (2) | |
f4b9d6a5 | 370 | returns 0, the lock is successful. |
c13182ef | 371 | Otherwise, use |
fea681da MK |
372 | .BR stat (2) |
373 | on the unique file to check if its link count has increased to 2, | |
374 | in which case the lock is also successful. | |
375 | .TP | |
1c1e15ed MK |
376 | .B O_LARGEFILE |
377 | (LFS) | |
378 | Allow files whose sizes cannot be represented in an | |
8478ee02 | 379 | .I off_t |
1c1e15ed | 380 | (but can be represented in an |
8478ee02 | 381 | .IR off64_t ) |
1c1e15ed | 382 | to be opened. |
c13182ef | 383 | The |
bcdd964e | 384 | .B _LARGEFILE64_SOURCE |
e417acb0 MK |
385 | macro must be defined |
386 | (before including | |
387 | .I any | |
388 | header files) | |
389 | in order to obtain this definition. | |
c13182ef | 390 | Setting the |
bcdd964e | 391 | .B _FILE_OFFSET_BITS |
9f3d8b28 MK |
392 | feature test macro to 64 (rather than using |
393 | .BR O_LARGEFILE ) | |
12e263f1 | 394 | is the preferred |
9f3d8b28 | 395 | method of accessing large files on 32-bit systems (see |
2dcbf4f7 | 396 | .BR feature_test_macros (7)). |
1c1e15ed | 397 | .TP |
fe75ec04 | 398 | .BR O_NOATIME " (Since Linux 2.6.8)" |
1bb72c96 MK |
399 | Do not update the file last access time |
400 | .RI ( st_atime | |
401 | in the inode) | |
310b7919 | 402 | when the file is |
1c1e15ed MK |
403 | .BR read (2). |
404 | This flag is intended for use by indexing or backup programs, | |
405 | where its use can significantly reduce the amount of disk activity. | |
9ee4a2b6 | 406 | This flag may not be effective on all filesystems. |
1c1e15ed | 407 | One example is NFS, where the server maintains the access time. |
0e1ad98c | 408 | .\" The O_NOATIME flag also affects the treatment of st_atime |
92057f4d | 409 | .\" by mmap() and readdir(2), MTK, Dec 04. |
1c1e15ed | 410 | .TP |
fea681da MK |
411 | .B O_NOCTTY |
412 | If | |
413 | .I pathname | |
5503c85e | 414 | refers to a terminal device\(emsee |
1bb72c96 MK |
415 | .BR tty (4)\(emit |
416 | will not become the process's controlling terminal even if the | |
fea681da MK |
417 | process does not have one. |
418 | .TP | |
1c1e15ed | 419 | .B O_NOFOLLOW |
a8d55537 | 420 | If \fIpathname\fP is a symbolic link, then the open fails. |
c13182ef | 421 | This is a FreeBSD extension, which was added to Linux in version 2.1.126. |
1c1e15ed | 422 | Symbolic links in earlier components of the pathname will still be |
e366dbc4 | 423 | followed. |
1135dbe1 MK |
424 | See also |
425 | .BR O_NOPATH | |
426 | below. | |
e366dbc4 MK |
427 | .\" The headers from glibc 2.0.100 and later include a |
428 | .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if | |
a8d55537 | 429 | .\" used\fP. |
fea681da MK |
430 | .TP |
431 | .BR O_NONBLOCK " or " O_NDELAY | |
ff40dbb3 | 432 | When possible, the file is opened in nonblocking mode. |
c13182ef | 433 | Neither the |
1c1e15ed | 434 | .BR open () |
fea681da MK |
435 | nor any subsequent operations on the file descriptor which is |
436 | returned will cause the calling process to wait. | |
437 | For the handling of FIFOs (named pipes), see also | |
af5b2ef2 | 438 | .BR fifo (7). |
db28bfac | 439 | For a discussion of the effect of |
0daa9e92 | 440 | .B O_NONBLOCK |
db28bfac MK |
441 | in conjunction with mandatory file locks and with file leases, see |
442 | .BR fcntl (2). | |
fea681da | 443 | .TP |
1135dbe1 MK |
444 | .BR O_PATH " (since Linux 2.6.39)" |
445 | .\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd | |
446 | .\" commit 326be7b484843988afe57566b627fb7a70beac56 | |
447 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
448 | .\" | |
449 | .\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496 | |
450 | .\" Subject: Re: [PATCH] open(2): document O_PATH | |
451 | .\" Newsgroups: gmane.linux.man, gmane.linux.kernel | |
452 | .\" | |
1135dbe1 | 453 | Obtain a file descriptor that can be used for two purposes: |
9ee4a2b6 | 454 | to indicate a location in the filesystem tree and |
1135dbe1 MK |
455 | to perform operations that act purely at the file descriptor level. |
456 | The file itself is not opened, and other file operations (e.g., | |
457 | .BR read (2), | |
458 | .BR write (2), | |
459 | .BR fchmod (2), | |
460 | .BR fchown (2), | |
461 | .BR fgetxattr (2)) | |
462 | fail with the error | |
463 | .BR EBADF . | |
464 | ||
465 | The following operations | |
466 | .I can | |
467 | be performed on the resulting file descriptor: | |
468 | .RS | |
469 | .IP * 3 | |
470 | .BR close (2); | |
471 | .BR fchdir (2) | |
472 | (since Linux 3.5); | |
473 | .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24 | |
474 | .BR fstat (2) | |
475 | (since Linux 3.6). | |
476 | .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2 | |
477 | .IP * | |
478 | Duplicating the file descriptor | |
479 | .RB ( dup (2), | |
480 | .BR fcntl (2) | |
481 | .BR F_DUPFD , | |
482 | etc.). | |
483 | .IP * | |
484 | Getting and setting file descriptor flags | |
485 | .RB ( fcntl (2) | |
486 | .BR F_GETFD | |
487 | and | |
488 | .BR F_SETFD ). | |
09f677a3 MK |
489 | .IP * |
490 | Retrieving open file status flags using the | |
491 | .BR fcntl (2) | |
13a082cb | 492 | .BR F_GETFL |
09f677a3 MK |
493 | operation: the returned flags will include the bit |
494 | .BR O_PATH . | |
495 | ||
1135dbe1 MK |
496 | .IP * |
497 | Passing the file descriptor as the | |
498 | .IR dirfd | |
499 | argument of | |
500 | .BR openat (2) | |
501 | and the other "*at()" system calls. | |
502 | .IP * | |
503 | Passing the file descriptor to another process via a UNIX domain socket | |
504 | (see | |
505 | .BR SCM_RIGHTS | |
506 | in | |
507 | .BR unix (7)). | |
508 | .RE | |
509 | .IP | |
510 | When | |
511 | .B O_PATH | |
512 | is specified in | |
513 | .IR flags , | |
514 | flag bits other than | |
515 | .BR O_DIRECTORY | |
516 | and | |
517 | .BR O_NOFOLLOW | |
518 | are ignored. | |
519 | ||
520 | If the | |
521 | .BR O_NOFOLLOW | |
522 | flag is also specified, | |
523 | then the call returns a file descriptor referring to the symbolic link. | |
524 | This file descriptor can be used as the | |
525 | .I dirfd | |
526 | argument in calls to | |
527 | .BR fchownat (2), | |
528 | .BR fstatat (2), | |
529 | .BR linkat (2), | |
530 | and | |
531 | .BR readlinkat (2) | |
532 | with an empty pathname to have the calls operate on the symbolic link. | |
533 | .TP | |
fea681da | 534 | .B O_SYNC |
c13182ef MK |
535 | The file is opened for synchronous I/O. |
536 | Any | |
0bfa087b | 537 | .BR write (2)s |
fea681da MK |
538 | on the resulting file descriptor will block the calling process until |
539 | the data has been physically written to the underlying hardware. | |
b07cd0a9 | 540 | .IR "But see NOTES below" . |
fea681da | 541 | .TP |
1c1e15ed MK |
542 | .B O_TRUNC |
543 | If the file already exists and is a regular file and the open mode allows | |
682edefb MK |
544 | writing (i.e., is |
545 | .B O_RDWR | |
546 | or | |
547 | .BR O_WRONLY ) | |
548 | it will be truncated to length 0. | |
549 | If the file is a FIFO or terminal device file, the | |
550 | .B O_TRUNC | |
c13182ef | 551 | flag is ignored. |
682edefb MK |
552 | Otherwise the effect of |
553 | .B O_TRUNC | |
554 | is unspecified. | |
fea681da MK |
555 | .PP |
556 | Some of these optional flags can be altered using | |
0bfa087b | 557 | .BR fcntl (2) |
fea681da MK |
558 | after the file has been opened. |
559 | ||
1c1e15ed | 560 | .BR creat () |
fea681da | 561 | is equivalent to |
1c1e15ed | 562 | .BR open () |
fea681da MK |
563 | with |
564 | .I flags | |
565 | equal to | |
566 | .BR O_CREAT|O_WRONLY|O_TRUNC . | |
47297adb | 567 | .SH RETURN VALUE |
c13182ef MK |
568 | .BR open () |
569 | and | |
e1d6264d | 570 | .BR creat () |
1c1e15ed MK |
571 | return the new file descriptor, or \-1 if an error occurred |
572 | (in which case, | |
fea681da MK |
573 | .I errno |
574 | is set appropriately). | |
fea681da MK |
575 | .SH ERRORS |
576 | .TP | |
577 | .B EACCES | |
578 | The requested access to the file is not allowed, or search permission | |
579 | is denied for one of the directories in the path prefix of | |
580 | .IR pathname , | |
581 | or the file did not exist yet and write access to the parent directory | |
582 | is not allowed. | |
583 | (See also | |
ad7cc990 | 584 | .BR path_resolution (7).) |
fea681da | 585 | .TP |
a1f01685 MH |
586 | .B EDQUOT |
587 | Where | |
588 | .B O_CREAT | |
589 | is specified, the file does not exist, and the user's quota of disk | |
9ee4a2b6 | 590 | blocks or inodes on the filesystem has been exhausted. |
a1f01685 | 591 | .TP |
fea681da MK |
592 | .B EEXIST |
593 | .I pathname | |
594 | already exists and | |
595 | .BR O_CREAT " and " O_EXCL | |
596 | were used. | |
597 | .TP | |
598 | .B EFAULT | |
0daa9e92 | 599 | .I pathname |
e1d6264d | 600 | points outside your accessible address space. |
fea681da | 601 | .TP |
9f5773f7 | 602 | .B EFBIG |
7c7fb552 MK |
603 | See |
604 | .BR EOVERFLOW . | |
9f5773f7 | 605 | .TP |
e51412ea MK |
606 | .B EINTR |
607 | While blocked waiting to complete an open of a slow device | |
608 | (e.g., a FIFO; see | |
609 | .BR fifo (7)), | |
610 | the call was interrupted by a signal handler; see | |
611 | .BR signal (7). | |
612 | .TP | |
fea681da MK |
613 | .B EISDIR |
614 | .I pathname | |
615 | refers to a directory and the access requested involved writing | |
616 | (that is, | |
617 | .B O_WRONLY | |
618 | or | |
619 | .B O_RDWR | |
620 | is set). | |
621 | .TP | |
622 | .B ELOOP | |
623 | Too many symbolic links were encountered in resolving | |
624 | .IR pathname , | |
a8d55537 | 625 | or \fBO_NOFOLLOW\fP was specified but |
fea681da MK |
626 | .I pathname |
627 | was a symbolic link. | |
628 | .TP | |
629 | .B EMFILE | |
630 | The process already has the maximum number of files open. | |
631 | .TP | |
632 | .B ENAMETOOLONG | |
0daa9e92 | 633 | .I pathname |
e1d6264d | 634 | was too long. |
fea681da MK |
635 | .TP |
636 | .B ENFILE | |
637 | The system limit on the total number of open files has been reached. | |
638 | .TP | |
639 | .B ENODEV | |
640 | .I pathname | |
641 | refers to a device special file and no corresponding device exists. | |
682edefb MK |
642 | (This is a Linux kernel bug; in this situation |
643 | .B ENXIO | |
644 | must be returned.) | |
fea681da MK |
645 | .TP |
646 | .B ENOENT | |
682edefb MK |
647 | .B O_CREAT |
648 | is not set and the named file does not exist. | |
fea681da MK |
649 | Or, a directory component in |
650 | .I pathname | |
651 | does not exist or is a dangling symbolic link. | |
652 | .TP | |
653 | .B ENOMEM | |
654 | Insufficient kernel memory was available. | |
655 | .TP | |
656 | .B ENOSPC | |
657 | .I pathname | |
658 | was to be created but the device containing | |
659 | .I pathname | |
660 | has no room for the new file. | |
661 | .TP | |
662 | .B ENOTDIR | |
663 | A component used as a directory in | |
664 | .I pathname | |
a8d55537 | 665 | is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and |
fea681da MK |
666 | .I pathname |
667 | was not a directory. | |
668 | .TP | |
669 | .B ENXIO | |
682edefb MK |
670 | .BR O_NONBLOCK " | " O_WRONLY |
671 | is set, the named file is a FIFO and | |
fea681da MK |
672 | no process has the file open for reading. |
673 | Or, the file is a device special file and no corresponding device exists. | |
674 | .TP | |
7c7fb552 MK |
675 | .B EOVERFLOW |
676 | .I pathname | |
677 | refers to a regular file that is too large to be opened. | |
678 | The usual scenario here is that an application compiled | |
679 | on a 32-bit platform without | |
5e4dc269 | 680 | .I -D_FILE_OFFSET_BITS=64 |
7c7fb552 MK |
681 | tried to open a file whose size exceeds |
682 | .I (2<<31)-1 | |
683 | bits; | |
684 | see also | |
685 | .B O_LARGEFILE | |
686 | above. | |
687 | This is the error specified by POSIX.1-2001; | |
688 | in kernels before 2.6.24, Linux gave the error | |
689 | .B EFBIG | |
690 | for this case. | |
691 | .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253 | |
692 | .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW" | |
693 | .\" Reported 2006-10-03 | |
694 | .TP | |
1c1e15ed MK |
695 | .B EPERM |
696 | The | |
697 | .B O_NOATIME | |
698 | flag was specified, but the effective user ID of the caller | |
9ee4a2b6 | 699 | .\" Strictly speaking, it's the filesystem UID... (MTK) |
1c1e15ed MK |
700 | did not match the owner of the file and the caller was not privileged |
701 | .RB ( CAP_FOWNER ). | |
702 | .TP | |
fea681da MK |
703 | .B EROFS |
704 | .I pathname | |
9ee4a2b6 | 705 | refers to a file on a read-only filesystem and write access was |
fea681da MK |
706 | requested. |
707 | .TP | |
708 | .B ETXTBSY | |
709 | .I pathname | |
710 | refers to an executable image which is currently being executed and | |
711 | write access was requested. | |
d3952311 MK |
712 | .TP |
713 | .B EWOULDBLOCK | |
714 | The | |
715 | .B O_NONBLOCK | |
716 | flag was specified, and an incompatible lease was held on the file | |
717 | (see | |
718 | .BR fcntl (2)). | |
47297adb | 719 | .SH CONFORMING TO |
97c1eac8 | 720 | SVr4, 4.3BSD, POSIX.1-2001. |
fea681da | 721 | The |
fe75ec04 | 722 | .BR O_DIRECTORY , |
1c1e15ed | 723 | .BR O_NOATIME , |
1135dbe1 | 724 | .BR O_NOFOLLOW , |
fea681da | 725 | and |
1135dbe1 | 726 | .BR O_PATH |
9f91e36c | 727 | flags are Linux-specific, and one may need to define |
61b7c1e1 | 728 | .B _GNU_SOURCE |
e417acb0 MK |
729 | (before including |
730 | .I any | |
731 | header files) | |
61b7c1e1 | 732 | to obtain their definitions. |
9f91e36c MK |
733 | |
734 | The | |
735 | .BR O_CLOEXEC | |
736 | flag is not specified in POSIX.1-2001, | |
7c5f0513 | 737 | but is specified in POSIX.1-2008. |
9f91e36c | 738 | |
0daa9e92 | 739 | .B O_DIRECT |
fb7339df | 740 | is not specified in POSIX; one has to define |
fe75ec04 | 741 | .B _GNU_SOURCE |
e417acb0 MK |
742 | (before including |
743 | .I any | |
744 | header files) | |
fe75ec04 | 745 | to get its definition. |
a1d5f77c | 746 | .SH NOTES |
988db661 | 747 | Under Linux, the |
a1d5f77c MK |
748 | .B O_NONBLOCK |
749 | flag indicates that one wants to open | |
750 | but does not necessarily have the intention to read or write. | |
751 | This is typically used to open devices in order to get a file descriptor | |
752 | for use with | |
753 | .BR ioctl (2). | |
c734b9f2 MK |
754 | |
755 | Unlike the other values that can be specified in | |
756 | .IR flags , | |
757 | the | |
758 | .I "access mode" | |
759 | values | |
760 | .BR O_RDONLY ", " O_WRONLY ", and " O_RDWR , | |
761 | do not specify individual bits. | |
762 | Rather, they define the low order two bits of | |
763 | .IR flags , | |
764 | and are defined respectively as 0, 1, and 2. | |
765 | In other words, the combination | |
766 | .B "O_RDONLY | O_WRONLY" | |
767 | is a logical error, and certainly does not have the same meaning as | |
768 | .BR O_RDWR . | |
c8f2dd47 | 769 | Linux reserves the special, nonstandard access mode 3 (binary 11) in |
c734b9f2 MK |
770 | .I flags |
771 | to mean: | |
772 | check for read and write permission on the file and return a descriptor | |
773 | that can't be used for reading or writing. | |
c8f2dd47 | 774 | This nonstandard access mode is used by some Linux drivers to return a |
33a0ccb2 | 775 | descriptor that is to be used only for device-specific |
c734b9f2 MK |
776 | .BR ioctl (2) |
777 | operations. | |
778 | .\" See for example util-linux's disk-utils/setfdprm.c | |
779 | .\" For some background on access mode 3, see | |
780 | .\" http://thread.gmane.org/gmane.linux.kernel/653123 | |
781 | .\" "[RFC] correct flags to f_mode conversion in __dentry_open" | |
782 | .\" LKML, 12 Mar 2008 | |
fea681da MK |
783 | .LP |
784 | The (undefined) effect of | |
785 | .B O_RDONLY | O_TRUNC | |
c13182ef | 786 | varies among implementations. |
bcdd964e | 787 | On many systems the file is actually truncated. |
fea681da MK |
788 | .\" Linux 2.0, 2.5: truncate |
789 | .\" Solaris 5.7, 5.8: truncate | |
790 | .\" Irix 6.5: truncate | |
791 | .\" Tru64 5.1B: truncate | |
792 | .\" HP-UX 11.22: truncate | |
793 | .\" FreeBSD 4.7: truncate | |
a1d5f77c MK |
794 | .PP |
795 | There are many infelicities in the protocol underlying NFS, affecting | |
796 | amongst others | |
797 | .BR O_SYNC " and " O_NDELAY . | |
798 | ||
d9bfdb9c | 799 | POSIX provides for three different variants of synchronized I/O, |
015221ef CH |
800 | corresponding to the flags |
801 | .BR O_SYNC , | |
802 | .BR O_DSYNC , | |
803 | and | |
804 | .BR O_RSYNC . | |
33a0ccb2 | 805 | Currently (2.6.31), Linux implements only |
015221ef CH |
806 | .BR O_SYNC , |
807 | but glibc maps | |
808 | .B O_DSYNC | |
809 | and | |
810 | .B O_RSYNC | |
811 | to the same numerical value as | |
0a598d26 | 812 | .BR O_SYNC . |
9ee4a2b6 | 813 | Most Linux filesystems don't actually implement the POSIX |
015221ef CH |
814 | .B O_SYNC |
815 | semantics, which require all metadata updates of a write | |
7fac88a9 | 816 | to be on disk on returning to user space, but only the |
015221ef CH |
817 | .B O_DSYNC |
818 | semantics, which require only actual file data and metadata necessary | |
819 | to retrieve it to be on disk by the time the system call returns. | |
a1d5f77c MK |
820 | |
821 | Note that | |
822 | .BR open () | |
823 | can open device special files, but | |
824 | .BR creat () | |
825 | cannot create them; use | |
826 | .BR mknod (2) | |
827 | instead. | |
828 | .LP | |
9ee4a2b6 | 829 | On NFS filesystems with UID mapping enabled, |
a1d5f77c MK |
830 | .BR open () |
831 | may | |
75b94dc3 | 832 | return a file descriptor but, for example, |
a1d5f77c MK |
833 | .BR read (2) |
834 | requests are denied | |
835 | with \fBEACCES\fP. | |
836 | This is because the client performs | |
837 | .BR open () | |
838 | by checking the | |
839 | permissions, but UID mapping is performed by the server upon | |
840 | read and write requests. | |
841 | ||
842 | If the file is newly created, its | |
988db661 | 843 | .IR st_atime , |
a1d5f77c MK |
844 | .IR st_ctime , |
845 | .I st_mtime | |
846 | fields | |
847 | (respectively, time of last access, time of last status change, and | |
848 | time of last modification; see | |
849 | .BR stat (2)) | |
850 | are set | |
851 | to the current time, and so are the | |
852 | .I st_ctime | |
988db661 | 853 | and |
a1d5f77c MK |
854 | .I st_mtime |
855 | fields of the | |
856 | parent directory. | |
988db661 | 857 | Otherwise, if the file is modified because of the |
a1d5f77c MK |
858 | .B O_TRUNC |
859 | flag, its st_ctime and st_mtime fields are set to the current time. | |
ddc4d339 MK |
860 | .SS O_DIRECT |
861 | .LP | |
862 | The | |
863 | .B O_DIRECT | |
864 | flag may impose alignment restrictions on the length and address | |
7fac88a9 | 865 | of user-space buffers and the file offset of I/Os. |
ddc4d339 | 866 | In Linux alignment |
9ee4a2b6 | 867 | restrictions vary by filesystem and kernel version and might be |
ddc4d339 | 868 | absent entirely. |
9ee4a2b6 | 869 | However there is currently no filesystem\-independent |
ddc4d339 | 870 | interface for an application to discover these restrictions for a given |
9ee4a2b6 MK |
871 | file or filesystem. |
872 | Some filesystems provide their own interfaces | |
ddc4d339 MK |
873 | for doing so, for example the |
874 | .B XFS_IOC_DIOINFO | |
875 | operation in | |
876 | .BR xfsctl (3). | |
877 | .LP | |
85c2bdba MK |
878 | Under Linux 2.4, transfer sizes, and the alignment of the user buffer |
879 | and the file offset must all be multiples of the logical block size | |
9ee4a2b6 | 880 | of the filesystem. |
04cd7f64 | 881 | Under Linux 2.6, alignment to 512-byte boundaries suffices. |
1847167b NP |
882 | .LP |
883 | .B O_DIRECT | |
884 | I/Os should never be run concurrently with the | |
04cd7f64 | 885 | .BR fork (2) |
1847167b NP |
886 | system call, |
887 | if the memory buffer is a private mapping | |
888 | (i.e., any mapping created with the | |
02ace852 | 889 | .BR mmap (2) |
1847167b | 890 | .BR MAP_PRIVATE |
0ab8aeec | 891 | flag; |
1847167b NP |
892 | this includes memory allocated on the heap and statically allocated buffers). |
893 | Any such I/Os, whether submitted via an asynchronous I/O interface or from | |
894 | another thread in the process, | |
895 | should be completed before | |
896 | .BR fork (2) | |
897 | is called. | |
898 | Failure to do so can result in data corruption and undefined behavior in | |
899 | parent and child processes. | |
900 | This restriction does not apply when the memory buffer for the | |
901 | .B O_DIRECT | |
902 | I/Os was created using | |
903 | .BR shmat (2) | |
904 | or | |
905 | .BR mmap (2) | |
906 | with the | |
907 | .B MAP_SHARED | |
908 | flag. | |
909 | Nor does this restriction apply when the memory buffer has been advised as | |
910 | .B MADV_DONTFORK | |
0ab8aeec | 911 | with |
02ace852 | 912 | .BR madvise (2), |
1847167b NP |
913 | ensuring that it will not be available |
914 | to the child after | |
915 | .BR fork (2). | |
ddc4d339 MK |
916 | .LP |
917 | The | |
918 | .B O_DIRECT | |
919 | flag was introduced in SGI IRIX, where it has alignment | |
920 | restrictions similar to those of Linux 2.4. | |
921 | IRIX has also a | |
922 | .BR fcntl (2) | |
923 | call to query appropriate alignments, and sizes. | |
924 | FreeBSD 4.x introduced | |
925 | a flag of the same name, but without alignment restrictions. | |
926 | .LP | |
927 | .B O_DIRECT | |
928 | support was added under Linux in kernel version 2.4.10. | |
929 | Older Linux kernels simply ignore this flag. | |
9ee4a2b6 | 930 | Some filesystems may not implement the flag and |
ddc4d339 MK |
931 | .BR open () |
932 | will fail with | |
933 | .B EINVAL | |
934 | if it is used. | |
935 | .LP | |
936 | Applications should avoid mixing | |
937 | .B O_DIRECT | |
938 | and normal I/O to the same file, | |
939 | and especially to overlapping byte regions in the same file. | |
9ee4a2b6 | 940 | Even when the filesystem correctly handles the coherency issues in |
ddc4d339 MK |
941 | this situation, overall I/O throughput is likely to be slower than |
942 | using either mode alone. | |
943 | Likewise, applications should avoid mixing | |
944 | .BR mmap (2) | |
945 | of files with direct I/O to the same files. | |
946 | .LP | |
947 | The behaviour of | |
948 | .B O_DIRECT | |
9ee4a2b6 | 949 | with NFS will differ from local filesystems. |
ddc4d339 MK |
950 | Older kernels, or |
951 | kernels configured in certain ways, may not support this combination. | |
952 | The NFS protocol does not support passing the flag to the server, so | |
953 | .B O_DIRECT | |
33a0ccb2 | 954 | I/O will bypass the page cache only on the client; the server may |
ddc4d339 MK |
955 | still cache the I/O. |
956 | The client asks the server to make the I/O | |
957 | synchronous to preserve the synchronous semantics of | |
958 | .BR O_DIRECT . | |
959 | Some servers will perform poorly under these circumstances, especially | |
960 | if the I/O size is small. | |
961 | Some servers may also be configured to | |
962 | lie to clients about the I/O having reached stable storage; this | |
963 | will avoid the performance penalty at some risk to data integrity | |
964 | in the event of server power failure. | |
965 | The Linux NFS client places no alignment restrictions on | |
966 | .B O_DIRECT | |
967 | I/O. | |
968 | .PP | |
969 | In summary, | |
970 | .B O_DIRECT | |
971 | is a potentially powerful tool that should be used with caution. | |
972 | It is recommended that applications treat use of | |
973 | .B O_DIRECT | |
974 | as a performance option which is disabled by default. | |
975 | .PP | |
976 | .RS | |
fea681da MK |
977 | "The thing that has always disturbed me about O_DIRECT is that the whole |
978 | interface is just stupid, and was probably designed by a deranged monkey | |
5503c85e | 979 | on some serious mind-controlling substances."\(emLinus |
ddc4d339 MK |
980 | .RE |
981 | .SH BUGS | |
b50582eb MK |
982 | Currently, it is not possible to enable signal-driven |
983 | I/O by specifying | |
984 | .B O_ASYNC | |
c13182ef | 985 | when calling |
b50582eb MK |
986 | .BR open (); |
987 | use | |
988 | .BR fcntl (2) | |
989 | to enable this flag. | |
0e1ad98c | 990 | .\" FIXME . Check bugzilla report on open(O_ASYNC) |
92057f4d | 991 | .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 |
47297adb | 992 | .SH SEE ALSO |
a3bf8022 MK |
993 | .BR chmod (2), |
994 | .BR chown (2), | |
fea681da | 995 | .BR close (2), |
e366dbc4 | 996 | .BR dup (2), |
fea681da MK |
997 | .BR fcntl (2), |
998 | .BR link (2), | |
1f6ceb40 | 999 | .BR lseek (2), |
fea681da | 1000 | .BR mknod (2), |
e366dbc4 | 1001 | .BR mmap (2), |
f0c34053 | 1002 | .BR mount (2), |
28c54d45 | 1003 | .BR openat (2), |
fea681da MK |
1004 | .BR read (2), |
1005 | .BR socket (2), | |
1006 | .BR stat (2), | |
1007 | .BR umask (2), | |
1008 | .BR unlink (2), | |
1009 | .BR write (2), | |
1010 | .BR fopen (3), | |
f0c34053 | 1011 | .BR fifo (7), |
a9cfde1d MK |
1012 | .BR path_resolution (7), |
1013 | .BR symlink (7) |