]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; | |
4 | .\" 1993 Michael Haardt, Ian Jackson. | |
ddc4d339 | 5 | .\" 2008 Greg Banks |
fea681da MK |
6 | .\" |
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. | |
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 MK |
48 | .\" O_TTYINIT. Eventually these may need to be documented. --mtk |
49 | .\" | |
50 | .TH OPEN 2 2008-04-08 "Linux" "Linux Programmer's Manual" | |
fea681da MK |
51 | .SH NAME |
52 | open, creat \- open and possibly create a file or device | |
53 | .SH SYNOPSIS | |
54 | .nf | |
55 | .B #include <sys/types.h> | |
56 | .B #include <sys/stat.h> | |
57 | .B #include <fcntl.h> | |
58 | .sp | |
59 | .BI "int open(const char *" pathname ", int " flags ); | |
60 | .BI "int open(const char *" pathname ", int " flags ", mode_t " mode ); | |
5895e7eb | 61 | |
fea681da MK |
62 | .BI "int creat(const char *" pathname ", mode_t " mode ); |
63 | .fi | |
64 | .SH DESCRIPTION | |
e366dbc4 | 65 | Given a |
0daa9e92 | 66 | .I pathname |
e366dbc4 | 67 | for a file, |
1f6ceb40 | 68 | .BR open () |
c13182ef | 69 | returns a file descriptor, a small, non-negative integer |
e366dbc4 MK |
70 | for use in subsequent system calls |
71 | .RB ( read "(2), " write "(2), " lseek "(2), " fcntl "(2), etc.)." | |
72 | The file descriptor returned by a successful call will be | |
2c4bff36 | 73 | the lowest-numbered file descriptor not currently open for the process. |
e366dbc4 | 74 | .PP |
fe75ec04 | 75 | By default, the new file descriptor is set to remain open across an |
e366dbc4 | 76 | .BR execve (2) |
1f6ceb40 MK |
77 | (i.e., the |
78 | .B FD_CLOEXEC | |
79 | file descriptor flag described in | |
80 | .BR fcntl (2) | |
fe75ec04 MK |
81 | is initially disabled; the Linux-specific |
82 | .B O_CLOEXEC | |
83 | flag, described below, can be used to change this default). | |
1f6ceb40 | 84 | The file offset is set to the beginning of the file (see |
c13182ef | 85 | .BR lseek (2)). |
e366dbc4 MK |
86 | .PP |
87 | A call to | |
88 | .BR open () | |
89 | creates a new | |
90 | .IR "open file description" , | |
91 | an entry in the system-wide table of open files. | |
e366dbc4 MK |
92 | This entry records the file offset and the file status flags |
93 | (modifiable via the | |
0bfa087b | 94 | .BR fcntl (2) |
e366dbc4 MK |
95 | .B F_SETFL |
96 | operation). | |
2c4bff36 MK |
97 | A file descriptor is a reference to one of these entries; |
98 | this reference is unaffected if | |
99 | .I pathname | |
100 | is subsequently removed or modified to refer to a different file. | |
e366dbc4 | 101 | The new open file description is initially not shared |
2c4bff36 MK |
102 | with any other process, |
103 | but sharing may arise via | |
104 | .BR fork (2). | |
e366dbc4 | 105 | .PP |
fea681da MK |
106 | The parameter |
107 | .I flags | |
e366dbc4 MK |
108 | must include one of the following |
109 | .IR "access modes" : | |
c7992edc | 110 | .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR . |
e366dbc4 MK |
111 | These request opening the file read-only, write-only, or read/write, |
112 | respectively. | |
bfe9ba67 MK |
113 | |
114 | In addition, zero or more file creation flags and file status flags | |
c13182ef | 115 | can be |
fea681da | 116 | .RI bitwise- or 'd |
e366dbc4 | 117 | in |
bfe9ba67 | 118 | .IR flags . |
c13182ef MK |
119 | The |
120 | .I file creation flags | |
121 | are | |
bfe9ba67 | 122 | .BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", and " O_TRUNC . |
c13182ef MK |
123 | The |
124 | .I file status flags | |
bfe9ba67 MK |
125 | are all of the remaining flags listed below. |
126 | The distinction between these two groups of flags is that | |
127 | the file status flags can be retrieved and (in some cases) | |
128 | modified using | |
129 | .BR fcntl (2). | |
130 | The full list of file creation flags and file status flags is as follows: | |
fea681da | 131 | .TP |
1c1e15ed | 132 | .B O_APPEND |
c13182ef MK |
133 | The file is opened in append mode. |
134 | Before each | |
0bfa087b | 135 | .BR write (2), |
1e568304 | 136 | the file offset is positioned at the end of the file, |
1c1e15ed | 137 | as if with |
0bfa087b | 138 | .BR lseek (2). |
1c1e15ed MK |
139 | .B O_APPEND |
140 | may lead to corrupted files on NFS file systems if more than one process | |
c13182ef MK |
141 | appends data to a file at once. |
142 | This is because NFS does not support | |
1c1e15ed MK |
143 | appending to a file, so the client kernel has to simulate it, which |
144 | can't be done without a race condition. | |
145 | .TP | |
146 | .B O_ASYNC | |
b50582eb | 147 | Enable signal-driven I/O: |
8bd58774 MK |
148 | generate a signal |
149 | .RB ( SIGIO | |
150 | by default, but this can be changed via | |
1c1e15ed MK |
151 | .BR fcntl (2)) |
152 | when input or output becomes possible on this file descriptor. | |
c13182ef | 153 | This feature is only available for terminals, pseudo-terminals, |
1f6ceb40 MK |
154 | sockets, and (since Linux 2.6) pipes and FIFOs. |
155 | See | |
1c1e15ed MK |
156 | .BR fcntl (2) |
157 | for further details. | |
fe75ec04 MK |
158 | .TP |
159 | .BR O_CLOEXEC " (Since Linux 2.6.23)" | |
160 | Enable the close-on-exec flag for the new file descriptor. | |
fb7339df | 161 | Specifying this flag permits a program to avoid an additional |
fe75ec04 MK |
162 | .BR fcntl (2) |
163 | .B F_SETFD | |
164 | operation to set the | |
0daa9e92 | 165 | .B FD_CLOEXEC |
fe75ec04 MK |
166 | flag. |
167 | Additionally, | |
168 | use of this flag is essential in some multithreaded programs | |
169 | since using a separate | |
170 | .BR fcntl (2) | |
171 | .B F_SETFD | |
172 | operation to set the | |
0daa9e92 | 173 | .B FD_CLOEXEC |
fe75ec04 MK |
174 | flag does not suffice to avoid race conditions |
175 | where one thread opens a file descriptor at the same | |
176 | time as another thread does a | |
177 | .BR fork (2) | |
178 | plus | |
179 | .BR execve (2). | |
180 | .\" This flag fixes only one form of the race condition; | |
181 | .\" The race can also occur with, for example, descriptors | |
182 | .\" returned by accept(), pipe(), etc. | |
1c1e15ed | 183 | .TP |
fea681da MK |
184 | .B O_CREAT |
185 | If the file does not exist it will be created. | |
186 | The owner (user ID) of the file is set to the effective user ID | |
c13182ef MK |
187 | of the process. |
188 | The group ownership (group ID) is set either to | |
fea681da | 189 | the effective group ID of the process or to the group ID of the |
24d01c53 | 190 | parent directory (depending on file system type and mount options, |
8b39ad66 | 191 | and the mode of the parent directory, see the mount options |
fea681da MK |
192 | .I bsdgroups |
193 | and | |
194 | .I sysvgroups | |
8b39ad66 | 195 | described in |
fea681da | 196 | .BR mount (8)). |
8b39ad66 MK |
197 | .\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and |
198 | .\" XFS (since 2.6.14). | |
4e698277 MK |
199 | .RS |
200 | .PP | |
201 | .I mode | |
202 | specifies the permissions to use in case a new file is created. | |
203 | This argument must be supplied when | |
204 | .B O_CREAT | |
205 | is specified in | |
206 | .IR flags ; | |
207 | if | |
208 | .B O_CREAT | |
209 | is not specified, then | |
210 | .I mode | |
211 | is ignored. | |
212 | The effective permissions are modified by | |
213 | the process's | |
214 | .I umask | |
215 | in the usual way: The permissions of the created file are | |
84a275c4 | 216 | .IR "(mode\ &\ ~umask)" . |
4e698277 MK |
217 | Note that this mode only applies to future accesses of the |
218 | newly created file; the | |
219 | .BR open () | |
220 | call that creates a read-only file may well return a read/write | |
221 | file descriptor. | |
222 | .PP | |
223 | The following symbolic constants are provided for | |
224 | .IR mode : | |
225 | .TP 9 | |
226 | .B S_IRWXU | |
227 | 00700 user (file owner) has read, write and execute permission | |
228 | .TP | |
229 | .B S_IRUSR | |
230 | 00400 user has read permission | |
231 | .TP | |
232 | .B S_IWUSR | |
233 | 00200 user has write permission | |
234 | .TP | |
235 | .B S_IXUSR | |
236 | 00100 user has execute permission | |
237 | .TP | |
238 | .B S_IRWXG | |
239 | 00070 group has read, write and execute permission | |
240 | .TP | |
241 | .B S_IRGRP | |
242 | 00040 group has read permission | |
243 | .TP | |
244 | .B S_IWGRP | |
245 | 00020 group has write permission | |
246 | .TP | |
247 | .B S_IXGRP | |
248 | 00010 group has execute permission | |
249 | .TP | |
250 | .B S_IRWXO | |
251 | 00007 others have read, write and execute permission | |
252 | .TP | |
253 | .B S_IROTH | |
254 | 00004 others have read permission | |
255 | .TP | |
256 | .B S_IWOTH | |
257 | 00002 others have write permission | |
258 | .TP | |
259 | .B S_IXOTH | |
260 | 00001 others have execute permission | |
261 | .RE | |
fea681da | 262 | .TP |
ddc4d339 | 263 | .BR O_DIRECT " (Since Linux 2.4.10)" |
1c1e15ed MK |
264 | Try to minimize cache effects of the I/O to and from this file. |
265 | In general this will degrade performance, but it is useful in | |
266 | special situations, such as when applications do their own caching. | |
267 | File I/O is done directly to/from user space buffers. | |
75b94dc3 | 268 | The I/O is synchronous, that is, at the completion of a |
1c1e15ed MK |
269 | .BR read (2) |
270 | or | |
e366dbc4 | 271 | .BR write (2), |
ddc4d339 MK |
272 | data is guaranteed to have been transferred. See |
273 | .B NOTES | |
274 | below for further discussion. | |
9b54d4fa | 275 | .sp |
c13182ef | 276 | A semantically similar (but deprecated) interface for block devices |
9b54d4fa | 277 | is described in |
1c1e15ed MK |
278 | .BR raw (8). |
279 | .TP | |
280 | .B O_DIRECTORY | |
a8d55537 | 281 | If \fIpathname\fP is not a directory, cause the open to fail. |
9f8d688a MK |
282 | .\" But see the following and its replies: |
283 | .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2 | |
284 | .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail | |
285 | .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored. | |
8382f16d | 286 | This flag is Linux-specific, and was added in kernel version 2.1.126, to |
60a90ecd MK |
287 | avoid denial-of-service problems if |
288 | .BR opendir (3) | |
289 | is called on a | |
1c1e15ed | 290 | FIFO or tape device, but should not be used outside of the |
9e370fba MK |
291 | implementation of |
292 | .BR opendir (3). | |
1c1e15ed | 293 | .TP |
fea681da | 294 | .B O_EXCL |
f4b9d6a5 MK |
295 | Ensure that this call creates the file: |
296 | if this flag is specified in conjunction with | |
fea681da | 297 | .BR O_CREAT , |
f4b9d6a5 MK |
298 | and |
299 | .I pathname | |
300 | already exists, then | |
1c1e15ed | 301 | .BR open () |
c13182ef | 302 | will fail. |
f4b9d6a5 MK |
303 | The behavior of |
304 | .B O_EXCL | |
305 | is undefined if | |
306 | .B O_CREAT | |
307 | is not specified. | |
308 | ||
309 | When these two flags are specified, symbolic links are not followed: | |
310 | .\" POSIX.1-2001 explicitly requires this behavior. | |
311 | if | |
312 | .I pathname | |
313 | is a symbolic link, then | |
314 | .BR open () | |
315 | fails regardless of where the symbolic link points to. | |
316 | ||
317 | .B O_EXCL | |
7db44341 | 318 | is not supported on NFSv2 or on Linux before kernel 2.6; |
f4b9d6a5 MK |
319 | it is supported on Linux 2.6 and later, with NFSv3 or later. |
320 | In environments where NFS | |
fea681da | 321 | .B O_EXCL |
f4b9d6a5 MK |
322 | support is not provided, programs that rely on it |
323 | for performing locking tasks will contain a race condition. | |
324 | Portable programs that want to perform atomic file locking using a lockfile, | |
325 | and need to avoid reliance on NFS support for | |
326 | .BR O_EXCL , | |
327 | can create a unique file on | |
328 | the same file system (e.g., incorporating hostname and PID), and use | |
fea681da | 329 | .BR link (2) |
c13182ef | 330 | to make a link to the lockfile. |
60a90ecd MK |
331 | If |
332 | .BR link (2) | |
f4b9d6a5 | 333 | returns 0, the lock is successful. |
c13182ef | 334 | Otherwise, use |
fea681da MK |
335 | .BR stat (2) |
336 | on the unique file to check if its link count has increased to 2, | |
337 | in which case the lock is also successful. | |
338 | .TP | |
1c1e15ed MK |
339 | .B O_LARGEFILE |
340 | (LFS) | |
341 | Allow files whose sizes cannot be represented in an | |
8478ee02 | 342 | .I off_t |
1c1e15ed | 343 | (but can be represented in an |
8478ee02 | 344 | .IR off64_t ) |
1c1e15ed | 345 | to be opened. |
c13182ef | 346 | The |
bcdd964e MK |
347 | .B _LARGEFILE64_SOURCE |
348 | macro must be defined in order to obtain this definition. | |
c13182ef | 349 | Setting the |
bcdd964e | 350 | .B _FILE_OFFSET_BITS |
9f3d8b28 MK |
351 | feature test macro to 64 (rather than using |
352 | .BR O_LARGEFILE ) | |
353 | is the preferred method of obtaining | |
354 | method of accessing large files on 32-bit systems (see | |
2dcbf4f7 | 355 | .BR feature_test_macros (7)). |
1c1e15ed | 356 | .TP |
fe75ec04 | 357 | .BR O_NOATIME " (Since Linux 2.6.8)" |
310b7919 MK |
358 | Do not update the file last access time (st_atime in the inode) |
359 | when the file is | |
1c1e15ed MK |
360 | .BR read (2). |
361 | This flag is intended for use by indexing or backup programs, | |
362 | where its use can significantly reduce the amount of disk activity. | |
24d01c53 | 363 | This flag may not be effective on all file systems. |
1c1e15ed | 364 | One example is NFS, where the server maintains the access time. |
0e1ad98c | 365 | .\" The O_NOATIME flag also affects the treatment of st_atime |
92057f4d | 366 | .\" by mmap() and readdir(2), MTK, Dec 04. |
1c1e15ed | 367 | .TP |
fea681da MK |
368 | .B O_NOCTTY |
369 | If | |
370 | .I pathname | |
371 | refers to a terminal device \(em see | |
372 | .BR tty (4) | |
373 | \(em it will not become the process's controlling terminal even if the | |
374 | process does not have one. | |
375 | .TP | |
1c1e15ed | 376 | .B O_NOFOLLOW |
a8d55537 | 377 | If \fIpathname\fP is a symbolic link, then the open fails. |
c13182ef | 378 | This is a FreeBSD extension, which was added to Linux in version 2.1.126. |
1c1e15ed | 379 | Symbolic links in earlier components of the pathname will still be |
e366dbc4 MK |
380 | followed. |
381 | .\" The headers from glibc 2.0.100 and later include a | |
382 | .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if | |
a8d55537 | 383 | .\" used\fP. |
fea681da MK |
384 | .TP |
385 | .BR O_NONBLOCK " or " O_NDELAY | |
c13182ef MK |
386 | When possible, the file is opened in non-blocking mode. |
387 | Neither the | |
1c1e15ed | 388 | .BR open () |
fea681da MK |
389 | nor any subsequent operations on the file descriptor which is |
390 | returned will cause the calling process to wait. | |
391 | For the handling of FIFOs (named pipes), see also | |
af5b2ef2 | 392 | .BR fifo (7). |
db28bfac | 393 | For a discussion of the effect of |
0daa9e92 | 394 | .B O_NONBLOCK |
db28bfac MK |
395 | in conjunction with mandatory file locks and with file leases, see |
396 | .BR fcntl (2). | |
fea681da MK |
397 | .TP |
398 | .B O_SYNC | |
c13182ef MK |
399 | The file is opened for synchronous I/O. |
400 | Any | |
0bfa087b | 401 | .BR write (2)s |
fea681da MK |
402 | on the resulting file descriptor will block the calling process until |
403 | the data has been physically written to the underlying hardware. | |
b07cd0a9 | 404 | .IR "But see NOTES below" . |
fea681da | 405 | .TP |
1c1e15ed MK |
406 | .B O_TRUNC |
407 | If the file already exists and is a regular file and the open mode allows | |
682edefb MK |
408 | writing (i.e., is |
409 | .B O_RDWR | |
410 | or | |
411 | .BR O_WRONLY ) | |
412 | it will be truncated to length 0. | |
413 | If the file is a FIFO or terminal device file, the | |
414 | .B O_TRUNC | |
c13182ef | 415 | flag is ignored. |
682edefb MK |
416 | Otherwise the effect of |
417 | .B O_TRUNC | |
418 | is unspecified. | |
fea681da MK |
419 | .PP |
420 | Some of these optional flags can be altered using | |
0bfa087b | 421 | .BR fcntl (2) |
fea681da MK |
422 | after the file has been opened. |
423 | ||
1c1e15ed | 424 | .BR creat () |
fea681da | 425 | is equivalent to |
1c1e15ed | 426 | .BR open () |
fea681da MK |
427 | with |
428 | .I flags | |
429 | equal to | |
430 | .BR O_CREAT|O_WRONLY|O_TRUNC . | |
431 | .SH "RETURN VALUE" | |
c13182ef MK |
432 | .BR open () |
433 | and | |
e1d6264d | 434 | .BR creat () |
1c1e15ed MK |
435 | return the new file descriptor, or \-1 if an error occurred |
436 | (in which case, | |
fea681da MK |
437 | .I errno |
438 | is set appropriately). | |
fea681da MK |
439 | .SH ERRORS |
440 | .TP | |
441 | .B EACCES | |
442 | The requested access to the file is not allowed, or search permission | |
443 | is denied for one of the directories in the path prefix of | |
444 | .IR pathname , | |
445 | or the file did not exist yet and write access to the parent directory | |
446 | is not allowed. | |
447 | (See also | |
ad7cc990 | 448 | .BR path_resolution (7).) |
fea681da MK |
449 | .TP |
450 | .B EEXIST | |
451 | .I pathname | |
452 | already exists and | |
453 | .BR O_CREAT " and " O_EXCL | |
454 | were used. | |
455 | .TP | |
456 | .B EFAULT | |
0daa9e92 | 457 | .I pathname |
e1d6264d | 458 | points outside your accessible address space. |
fea681da | 459 | .TP |
9f5773f7 MK |
460 | .B EFBIG |
461 | .I pathname | |
682edefb MK |
462 | refers to a regular file, too large to be opened; see |
463 | .B O_LARGEFILE | |
464 | above. | |
c13182ef | 465 | (POSIX.1-2001 specifies the error |
9f5773f7 MK |
466 | .B EOVERFLOW |
467 | for this case.) | |
0e1ad98c | 468 | .\" FIXME . Maybe this deviation from the standard will get repaired. |
9f5773f7 MK |
469 | .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253 |
470 | .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW" | |
471 | .\" Reported 2006-10-03 | |
472 | .TP | |
fea681da MK |
473 | .B EISDIR |
474 | .I pathname | |
475 | refers to a directory and the access requested involved writing | |
476 | (that is, | |
477 | .B O_WRONLY | |
478 | or | |
479 | .B O_RDWR | |
480 | is set). | |
481 | .TP | |
482 | .B ELOOP | |
483 | Too many symbolic links were encountered in resolving | |
484 | .IR pathname , | |
a8d55537 | 485 | or \fBO_NOFOLLOW\fP was specified but |
fea681da MK |
486 | .I pathname |
487 | was a symbolic link. | |
488 | .TP | |
489 | .B EMFILE | |
490 | The process already has the maximum number of files open. | |
491 | .TP | |
492 | .B ENAMETOOLONG | |
0daa9e92 | 493 | .I pathname |
e1d6264d | 494 | was too long. |
fea681da MK |
495 | .TP |
496 | .B ENFILE | |
497 | The system limit on the total number of open files has been reached. | |
498 | .TP | |
499 | .B ENODEV | |
500 | .I pathname | |
501 | refers to a device special file and no corresponding device exists. | |
682edefb MK |
502 | (This is a Linux kernel bug; in this situation |
503 | .B ENXIO | |
504 | must be returned.) | |
fea681da MK |
505 | .TP |
506 | .B ENOENT | |
682edefb MK |
507 | .B O_CREAT |
508 | is not set and the named file does not exist. | |
fea681da MK |
509 | Or, a directory component in |
510 | .I pathname | |
511 | does not exist or is a dangling symbolic link. | |
512 | .TP | |
513 | .B ENOMEM | |
514 | Insufficient kernel memory was available. | |
515 | .TP | |
516 | .B ENOSPC | |
517 | .I pathname | |
518 | was to be created but the device containing | |
519 | .I pathname | |
520 | has no room for the new file. | |
521 | .TP | |
522 | .B ENOTDIR | |
523 | A component used as a directory in | |
524 | .I pathname | |
a8d55537 | 525 | is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and |
fea681da MK |
526 | .I pathname |
527 | was not a directory. | |
528 | .TP | |
529 | .B ENXIO | |
682edefb MK |
530 | .BR O_NONBLOCK " | " O_WRONLY |
531 | is set, the named file is a FIFO and | |
fea681da MK |
532 | no process has the file open for reading. |
533 | Or, the file is a device special file and no corresponding device exists. | |
534 | .TP | |
1c1e15ed MK |
535 | .B EPERM |
536 | The | |
537 | .B O_NOATIME | |
538 | flag was specified, but the effective user ID of the caller | |
539 | .\" Strictly speaking, it's the file system UID... (MTK) | |
540 | did not match the owner of the file and the caller was not privileged | |
541 | .RB ( CAP_FOWNER ). | |
542 | .TP | |
fea681da MK |
543 | .B EROFS |
544 | .I pathname | |
24d01c53 | 545 | refers to a file on a read-only file system and write access was |
fea681da MK |
546 | requested. |
547 | .TP | |
548 | .B ETXTBSY | |
549 | .I pathname | |
550 | refers to an executable image which is currently being executed and | |
551 | write access was requested. | |
d3952311 MK |
552 | .TP |
553 | .B EWOULDBLOCK | |
554 | The | |
555 | .B O_NONBLOCK | |
556 | flag was specified, and an incompatible lease was held on the file | |
557 | (see | |
558 | .BR fcntl (2)). | |
fea681da | 559 | .SH "CONFORMING TO" |
97c1eac8 | 560 | SVr4, 4.3BSD, POSIX.1-2001. |
fea681da | 561 | The |
fe75ec04 | 562 | .BR O_DIRECTORY , |
1c1e15ed | 563 | .BR O_NOATIME , |
fea681da | 564 | and |
0daa9e92 | 565 | .B O_NOFOLLOW |
9f91e36c | 566 | flags are Linux-specific, and one may need to define |
61b7c1e1 MK |
567 | .B _GNU_SOURCE |
568 | to obtain their definitions. | |
9f91e36c MK |
569 | .\" FIXME . update the following sentence when POSIX.1-2008 is finalized. |
570 | ||
571 | The | |
572 | .BR O_CLOEXEC | |
573 | flag is not specified in POSIX.1-2001, | |
574 | but is planned for inclusion in the next revision of the standard; | |
61b7c1e1 | 575 | one has to define the |
fea681da | 576 | .B _GNU_SOURCE |
9f91e36c MK |
577 | macro to get its definitions. |
578 | ||
0daa9e92 | 579 | .B O_DIRECT |
fb7339df | 580 | is not specified in POSIX; one has to define |
fe75ec04 MK |
581 | .B _GNU_SOURCE |
582 | to get its definition. | |
a1d5f77c | 583 | .SH NOTES |
988db661 | 584 | Under Linux, the |
a1d5f77c MK |
585 | .B O_NONBLOCK |
586 | flag indicates that one wants to open | |
587 | but does not necessarily have the intention to read or write. | |
588 | This is typically used to open devices in order to get a file descriptor | |
589 | for use with | |
590 | .BR ioctl (2). | |
fea681da MK |
591 | .LP |
592 | The (undefined) effect of | |
593 | .B O_RDONLY | O_TRUNC | |
c13182ef | 594 | varies among implementations. |
bcdd964e | 595 | On many systems the file is actually truncated. |
fea681da MK |
596 | .\" Linux 2.0, 2.5: truncate |
597 | .\" Solaris 5.7, 5.8: truncate | |
598 | .\" Irix 6.5: truncate | |
599 | .\" Tru64 5.1B: truncate | |
600 | .\" HP-UX 11.22: truncate | |
601 | .\" FreeBSD 4.7: truncate | |
a1d5f77c MK |
602 | .PP |
603 | There are many infelicities in the protocol underlying NFS, affecting | |
604 | amongst others | |
605 | .BR O_SYNC " and " O_NDELAY . | |
606 | ||
d9bfdb9c | 607 | POSIX provides for three different variants of synchronized I/O, |
a8d55537 MK |
608 | corresponding to the flags \fBO_SYNC\fP, \fBO_DSYNC\fP and |
609 | \fBO_RSYNC\fP. | |
a1d5f77c MK |
610 | Currently (2.1.130) these are all synonymous under Linux. |
611 | ||
612 | Note that | |
613 | .BR open () | |
614 | can open device special files, but | |
615 | .BR creat () | |
616 | cannot create them; use | |
617 | .BR mknod (2) | |
618 | instead. | |
619 | .LP | |
620 | On NFS file systems with UID mapping enabled, | |
621 | .BR open () | |
622 | may | |
75b94dc3 | 623 | return a file descriptor but, for example, |
a1d5f77c MK |
624 | .BR read (2) |
625 | requests are denied | |
626 | with \fBEACCES\fP. | |
627 | This is because the client performs | |
628 | .BR open () | |
629 | by checking the | |
630 | permissions, but UID mapping is performed by the server upon | |
631 | read and write requests. | |
632 | ||
633 | If the file is newly created, its | |
988db661 | 634 | .IR st_atime , |
a1d5f77c MK |
635 | .IR st_ctime , |
636 | .I st_mtime | |
637 | fields | |
638 | (respectively, time of last access, time of last status change, and | |
639 | time of last modification; see | |
640 | .BR stat (2)) | |
641 | are set | |
642 | to the current time, and so are the | |
643 | .I st_ctime | |
988db661 | 644 | and |
a1d5f77c MK |
645 | .I st_mtime |
646 | fields of the | |
647 | parent directory. | |
988db661 | 648 | Otherwise, if the file is modified because of the |
a1d5f77c MK |
649 | .B O_TRUNC |
650 | flag, its st_ctime and st_mtime fields are set to the current time. | |
ddc4d339 MK |
651 | .SS O_DIRECT |
652 | .LP | |
653 | The | |
654 | .B O_DIRECT | |
655 | flag may impose alignment restrictions on the length and address | |
656 | of userspace buffers and the file offset of I/Os. | |
657 | In Linux alignment | |
24d01c53 | 658 | restrictions vary by file system and kernel version and might be |
ddc4d339 | 659 | absent entirely. |
24d01c53 | 660 | However there is currently no file system\-independent |
ddc4d339 | 661 | interface for an application to discover these restrictions for a given |
24d01c53 MK |
662 | file or file system. |
663 | Some file systems provide their own interfaces | |
ddc4d339 MK |
664 | for doing so, for example the |
665 | .B XFS_IOC_DIOINFO | |
666 | operation in | |
667 | .BR xfsctl (3). | |
668 | .LP | |
669 | Under Linux 2.4, transfer sizes, and the alignment of user buffer | |
670 | and file offset must all be multiples of the logical block size | |
671 | of the file system. | |
672 | Under Linux 2.6, alignment to 512-byte boundaries | |
673 | suffices. | |
674 | .LP | |
675 | The | |
676 | .B O_DIRECT | |
677 | flag was introduced in SGI IRIX, where it has alignment | |
678 | restrictions similar to those of Linux 2.4. | |
679 | IRIX has also a | |
680 | .BR fcntl (2) | |
681 | call to query appropriate alignments, and sizes. | |
682 | FreeBSD 4.x introduced | |
683 | a flag of the same name, but without alignment restrictions. | |
684 | .LP | |
685 | .B O_DIRECT | |
686 | support was added under Linux in kernel version 2.4.10. | |
687 | Older Linux kernels simply ignore this flag. | |
24d01c53 | 688 | Some file systems may not implement the flag and |
ddc4d339 MK |
689 | .BR open () |
690 | will fail with | |
691 | .B EINVAL | |
692 | if it is used. | |
693 | .LP | |
694 | Applications should avoid mixing | |
695 | .B O_DIRECT | |
696 | and normal I/O to the same file, | |
697 | and especially to overlapping byte regions in the same file. | |
24d01c53 | 698 | Even when the file system correctly handles the coherency issues in |
ddc4d339 MK |
699 | this situation, overall I/O throughput is likely to be slower than |
700 | using either mode alone. | |
701 | Likewise, applications should avoid mixing | |
702 | .BR mmap (2) | |
703 | of files with direct I/O to the same files. | |
704 | .LP | |
705 | The behaviour of | |
706 | .B O_DIRECT | |
24d01c53 | 707 | with NFS will differ from local file systems. |
ddc4d339 MK |
708 | Older kernels, or |
709 | kernels configured in certain ways, may not support this combination. | |
710 | The NFS protocol does not support passing the flag to the server, so | |
711 | .B O_DIRECT | |
712 | I/O will only bypass the page cache on the client; the server may | |
713 | still cache the I/O. | |
714 | The client asks the server to make the I/O | |
715 | synchronous to preserve the synchronous semantics of | |
716 | .BR O_DIRECT . | |
717 | Some servers will perform poorly under these circumstances, especially | |
718 | if the I/O size is small. | |
719 | Some servers may also be configured to | |
720 | lie to clients about the I/O having reached stable storage; this | |
721 | will avoid the performance penalty at some risk to data integrity | |
722 | in the event of server power failure. | |
723 | The Linux NFS client places no alignment restrictions on | |
724 | .B O_DIRECT | |
725 | I/O. | |
726 | .PP | |
727 | In summary, | |
728 | .B O_DIRECT | |
729 | is a potentially powerful tool that should be used with caution. | |
730 | It is recommended that applications treat use of | |
731 | .B O_DIRECT | |
732 | as a performance option which is disabled by default. | |
733 | .PP | |
734 | .RS | |
fea681da MK |
735 | "The thing that has always disturbed me about O_DIRECT is that the whole |
736 | interface is just stupid, and was probably designed by a deranged monkey | |
e9496f74 | 737 | on some serious mind-controlling substances." \(em Linus |
ddc4d339 MK |
738 | .RE |
739 | .SH BUGS | |
b50582eb MK |
740 | Currently, it is not possible to enable signal-driven |
741 | I/O by specifying | |
742 | .B O_ASYNC | |
c13182ef | 743 | when calling |
b50582eb MK |
744 | .BR open (); |
745 | use | |
746 | .BR fcntl (2) | |
747 | to enable this flag. | |
0e1ad98c | 748 | .\" FIXME . Check bugzilla report on open(O_ASYNC) |
92057f4d | 749 | .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 |
fea681da MK |
750 | .SH "SEE ALSO" |
751 | .BR close (2), | |
e366dbc4 | 752 | .BR dup (2), |
fea681da MK |
753 | .BR fcntl (2), |
754 | .BR link (2), | |
1f6ceb40 | 755 | .BR lseek (2), |
fea681da MK |
756 | .BR mknod (2), |
757 | .BR mount (2), | |
e366dbc4 | 758 | .BR mmap (2), |
28c54d45 | 759 | .BR openat (2), |
fea681da MK |
760 | .BR read (2), |
761 | .BR socket (2), | |
762 | .BR stat (2), | |
763 | .BR umask (2), | |
764 | .BR unlink (2), | |
765 | .BR write (2), | |
766 | .BR fopen (3), | |
50e5322c | 767 | .BR fifo (7), |
ad7cc990 MK |
768 | .BR feature_test_macros (7), |
769 | .BR path_resolution (7) |