]>
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. | |
5 | .\" | |
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. | |
14 | .\" | |
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. | |
22 | .\" | |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
25 | .\" | |
26 | .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> | |
27 | .\" Modified 1994-08-21 by Michael Haardt | |
28 | .\" Modified 1996-04-13 by Andries Brouwer <aeb@cwi.nl> | |
29 | .\" Modified 1996-05-13 by Thomas Koenig | |
30 | .\" Modified 1996-12-20 by Michael Haardt | |
31 | .\" Modified 1999-02-19 by Andries Brouwer <aeb@cwi.nl> | |
32 | .\" Modified 1998-11-28 by Joseph S. Myers <jsm28@hermes.cam.ac.uk> | |
33 | .\" Modified 1999-06-03 by Michael Haardt | |
305a0578 MK |
34 | .\" Modified 2002-05-07 by Michael Kerrisk <mtk-manpages@gmx.net> |
35 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk-manpages@gmx.net> | |
1c1e15ed MK |
36 | .\" 2004-12-08, mtk, reordered flags list alphabetically |
37 | .\" 2004-12-08, Martin Pool <mbp@sourcefrog.net> (& mtk), added O_NOATIME | |
fea681da | 38 | .\" |
e366dbc4 | 39 | .TH OPEN 2 2005-06-22 "Linux 2.6.12" "Linux Programmer's Manual" |
fea681da MK |
40 | .SH NAME |
41 | open, creat \- open and possibly create a file or device | |
42 | .SH SYNOPSIS | |
43 | .nf | |
44 | .B #include <sys/types.h> | |
45 | .B #include <sys/stat.h> | |
46 | .B #include <fcntl.h> | |
47 | .sp | |
48 | .BI "int open(const char *" pathname ", int " flags ); | |
49 | .BI "int open(const char *" pathname ", int " flags ", mode_t " mode ); | |
50 | .BI "int creat(const char *" pathname ", mode_t " mode ); | |
51 | .fi | |
52 | .SH DESCRIPTION | |
e366dbc4 MK |
53 | Given a |
54 | .IR pathname | |
55 | for a file, | |
1f6ceb40 | 56 | .BR open () |
e366dbc4 MK |
57 | returns a file descriptor, a small, non-negative integer |
58 | for use in subsequent system calls | |
59 | .RB ( read "(2), " write "(2), " lseek "(2), " fcntl "(2), etc.)." | |
60 | The file descriptor returned by a successful call will be | |
2c4bff36 | 61 | the lowest-numbered file descriptor not currently open for the process. |
e366dbc4 MK |
62 | .PP |
63 | The new file descriptor is set to remain open across an | |
64 | .BR execve (2) | |
1f6ceb40 MK |
65 | (i.e., the |
66 | .B FD_CLOEXEC | |
67 | file descriptor flag described in | |
68 | .BR fcntl (2) | |
69 | is initially disabled). | |
70 | The file offset is set to the beginning of the file (see | |
71 | .BR lseek (2)). | |
e366dbc4 MK |
72 | .PP |
73 | A call to | |
74 | .BR open () | |
75 | creates a new | |
76 | .IR "open file description" , | |
77 | an entry in the system-wide table of open files. | |
e366dbc4 MK |
78 | This entry records the file offset and the file status flags |
79 | (modifiable via the | |
80 | .BR fcntl () | |
81 | .B F_SETFL | |
82 | operation). | |
2c4bff36 MK |
83 | A file descriptor is a reference to one of these entries; |
84 | this reference is unaffected if | |
85 | .I pathname | |
86 | is subsequently removed or modified to refer to a different file. | |
e366dbc4 | 87 | The new open file description is initially not shared |
2c4bff36 MK |
88 | with any other process, |
89 | but sharing may arise via | |
90 | .BR fork (2). | |
e366dbc4 | 91 | .PP |
fea681da MK |
92 | The parameter |
93 | .I flags | |
e366dbc4 MK |
94 | must include one of the following |
95 | .IR "access modes" : | |
96 | .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR. | |
97 | These request opening the file read-only, write-only, or read/write, | |
98 | respectively. | |
99 | In addition, zero or more of the following may be | |
fea681da | 100 | .RI bitwise- or 'd |
e366dbc4 MK |
101 | in |
102 | .IR flags : | |
fea681da | 103 | .TP |
1c1e15ed MK |
104 | .B O_APPEND |
105 | The file is opened in append mode. Before each | |
106 | .BR write (), | |
1e568304 | 107 | the file offset is positioned at the end of the file, |
1c1e15ed MK |
108 | as if with |
109 | .BR lseek (). | |
110 | .B O_APPEND | |
111 | may lead to corrupted files on NFS file systems if more than one process | |
112 | appends data to a file at once. This is because NFS does not support | |
113 | appending to a file, so the client kernel has to simulate it, which | |
114 | can't be done without a race condition. | |
115 | .TP | |
116 | .B O_ASYNC | |
117 | .\" FIXME -- as far as I can tell O_ASYNC doesn't work for open(2), | |
118 | .\" only when set via fcntl(2) -- MTK, Dec 04 | |
119 | Generate a signal (SIGIO by default, but this can be changed via | |
120 | .BR fcntl (2)) | |
121 | when input or output becomes possible on this file descriptor. | |
1f6ceb40 MK |
122 | This feature is only available for terminals, pseudo-terminals, |
123 | sockets, and (since Linux 2.6) pipes and FIFOs. | |
124 | See | |
1c1e15ed MK |
125 | .BR fcntl (2) |
126 | for further details. | |
127 | .TP | |
fea681da MK |
128 | .B O_CREAT |
129 | If the file does not exist it will be created. | |
130 | The owner (user ID) of the file is set to the effective user ID | |
131 | of the process. The group ownership (group ID) is set either to | |
132 | the effective group ID of the process or to the group ID of the | |
133 | parent directory (depending on filesystem type and mount options, | |
134 | and the mode of the parent directory, see, e.g., the mount options | |
135 | .I bsdgroups | |
136 | and | |
137 | .I sysvgroups | |
138 | of the ext2 filesystem, as described in | |
139 | .BR mount (8)). | |
140 | .TP | |
1c1e15ed MK |
141 | .B O_DIRECT |
142 | Try to minimize cache effects of the I/O to and from this file. | |
143 | In general this will degrade performance, but it is useful in | |
144 | special situations, such as when applications do their own caching. | |
145 | File I/O is done directly to/from user space buffers. | |
e366dbc4 | 146 | The I/O is synchronous, i.e., at the completion of a |
1c1e15ed MK |
147 | .BR read (2) |
148 | or | |
e366dbc4 MK |
149 | .BR write (2), |
150 | data is guaranteed to have been transferred. | |
1c1e15ed MK |
151 | Under Linux 2.4 transfer sizes, and the alignment of user buffer |
152 | and file offset must all be multiples of the logical block size | |
153 | of the file system. Under Linux 2.6 alignment to 512-byte boundaries | |
154 | suffices. | |
155 | .\" Alignment should satisfy requirements for the underlying device | |
156 | .\" There may be coherency problems. | |
157 | .br | |
158 | A semantically similar interface for block devices is described in | |
159 | .BR raw (8). | |
160 | .TP | |
161 | .B O_DIRECTORY | |
162 | If \fIpathname\fR is not a directory, cause the open to fail. This | |
163 | flag is Linux-specific, and was added in kernel version 2.1.126, to | |
164 | avoid denial-of-service problems if \fBopendir\fR(3) is called on a | |
165 | FIFO or tape device, but should not be used outside of the | |
166 | implementation of \fBopendir\fR. | |
167 | .TP | |
fea681da MK |
168 | .B O_EXCL |
169 | When used with | |
170 | .BR O_CREAT , | |
171 | if the file already exists it is an error and the | |
1c1e15ed | 172 | .BR open () |
fea681da | 173 | will fail. In this context, a symbolic link exists, regardless |
1f6ceb40 | 174 | of where it points to. |
fea681da | 175 | .B O_EXCL |
1f6ceb40 | 176 | is broken on NFS file systems; programs which rely on it for performing |
fea681da | 177 | locking tasks will contain a race condition. The solution for performing |
1c1e15ed MK |
178 | atomic file locking using a lockfile is to create a unique file on |
179 | the same file system (e.g., incorporating hostname and pid), use | |
fea681da MK |
180 | .BR link (2) |
181 | to make a link to the lockfile. If \fBlink()\fP returns 0, the lock is | |
182 | successful. Otherwise, use | |
183 | .BR stat (2) | |
184 | on the unique file to check if its link count has increased to 2, | |
185 | in which case the lock is also successful. | |
186 | .TP | |
1c1e15ed MK |
187 | .B O_LARGEFILE |
188 | (LFS) | |
189 | Allow files whose sizes cannot be represented in an | |
190 | .B off_t | |
191 | (but can be represented in an | |
192 | .BR off64_t ) | |
193 | to be opened. | |
194 | .TP | |
195 | .B O_NOATIME | |
196 | (Since Linux 2.6.8) | |
310b7919 MK |
197 | Do not update the file last access time (st_atime in the inode) |
198 | when the file is | |
1c1e15ed MK |
199 | .BR read (2). |
200 | This flag is intended for use by indexing or backup programs, | |
201 | where its use can significantly reduce the amount of disk activity. | |
202 | This flag may not be effective on all filesystems. | |
203 | One example is NFS, where the server maintains the access time. | |
204 | .\" FIXME? This flag also affects the treatment of st_atime by mmap() | |
205 | .\" and readdir(2), MTK, Dec 04. | |
206 | .TP | |
fea681da MK |
207 | .B O_NOCTTY |
208 | If | |
209 | .I pathname | |
210 | refers to a terminal device \(em see | |
211 | .BR tty (4) | |
212 | \(em it will not become the process's controlling terminal even if the | |
213 | process does not have one. | |
214 | .TP | |
1c1e15ed MK |
215 | .B O_NOFOLLOW |
216 | If \fIpathname\fR is a symbolic link, then the open fails. This is a | |
217 | FreeBSD extension, which was added to Linux in version 2.1.126. | |
218 | Symbolic links in earlier components of the pathname will still be | |
e366dbc4 MK |
219 | followed. |
220 | .\" The headers from glibc 2.0.100 and later include a | |
221 | .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if | |
222 | .\" used\fR. | |
fea681da MK |
223 | .TP |
224 | .BR O_NONBLOCK " or " O_NDELAY | |
225 | When possible, the file is opened in non-blocking mode. Neither the | |
1c1e15ed | 226 | .BR open () |
fea681da MK |
227 | nor any subsequent operations on the file descriptor which is |
228 | returned will cause the calling process to wait. | |
229 | For the handling of FIFOs (named pipes), see also | |
230 | .BR fifo (4). | |
231 | This mode need not have any effect on files other than FIFOs. | |
232 | .TP | |
233 | .B O_SYNC | |
234 | The file is opened for synchronous I/O. Any | |
1c1e15ed | 235 | .BR write ()s |
fea681da MK |
236 | on the resulting file descriptor will block the calling process until |
237 | the data has been physically written to the underlying hardware. | |
238 | .I See RESTRICTIONS below, though. | |
239 | .TP | |
1c1e15ed MK |
240 | .B O_TRUNC |
241 | If the file already exists and is a regular file and the open mode allows | |
242 | writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0. | |
243 | If the file is a FIFO or terminal device file, the O_TRUNC | |
244 | flag is ignored. Otherwise the effect of O_TRUNC is unspecified. | |
fea681da MK |
245 | .PP |
246 | Some of these optional flags can be altered using | |
1c1e15ed | 247 | .BR fcntl () |
fea681da MK |
248 | after the file has been opened. |
249 | ||
250 | The argument | |
251 | .I mode | |
252 | specifies the permissions to use in case a new file is created. It is | |
253 | modified by the process's | |
254 | .BR umask | |
255 | in the usual way: the permissions of the created file are | |
256 | .BR "(mode & ~umask)" . | |
257 | Note that this mode only applies to future accesses of the | |
258 | newly created file; the | |
1c1e15ed | 259 | .BR open () |
fea681da MK |
260 | call that creates a read-only file may well return a read/write |
261 | file descriptor. | |
262 | .PP | |
263 | The following symbolic constants are provided for | |
264 | .IR mode : | |
265 | .TP | |
266 | .B S_IRWXU | |
267 | 00700 user (file owner) has read, write and execute permission | |
268 | .TP | |
269 | .B S_IRUSR (S_IREAD) | |
270 | 00400 user has read permission | |
271 | .TP | |
272 | .B S_IWUSR (S_IWRITE) | |
273 | 00200 user has write permission | |
274 | .TP | |
275 | .B S_IXUSR (S_IEXEC) | |
276 | 00100 user has execute permission | |
277 | .TP | |
278 | .B S_IRWXG | |
279 | 00070 group has read, write and execute permission | |
280 | .TP | |
281 | .B S_IRGRP | |
282 | 00040 group has read permission | |
283 | .TP | |
284 | .B S_IWGRP | |
285 | 00020 group has write permission | |
286 | .TP | |
287 | .B S_IXGRP | |
288 | 00010 group has execute permission | |
289 | .TP | |
290 | .B S_IRWXO | |
291 | 00007 others have read, write and execute permission | |
292 | .TP | |
293 | .B S_IROTH | |
294 | 00004 others have read permission | |
295 | .TP | |
296 | .B S_IWOTH | |
d301ee6c | 297 | 00002 others have write permission |
fea681da MK |
298 | .TP |
299 | .B S_IXOTH | |
300 | 00001 others have execute permission | |
301 | .PP | |
302 | .I mode | |
303 | must be specified when | |
304 | .B O_CREAT | |
305 | is in the | |
306 | .IR flags , | |
307 | and is ignored otherwise. | |
308 | ||
1c1e15ed | 309 | .BR creat () |
fea681da | 310 | is equivalent to |
1c1e15ed | 311 | .BR open () |
fea681da MK |
312 | with |
313 | .I flags | |
314 | equal to | |
315 | .BR O_CREAT|O_WRONLY|O_TRUNC . | |
316 | .SH "RETURN VALUE" | |
1c1e15ed MK |
317 | .BR open "() and " creat () |
318 | return the new file descriptor, or \-1 if an error occurred | |
319 | (in which case, | |
fea681da MK |
320 | .I errno |
321 | is set appropriately). | |
322 | Note that | |
1c1e15ed | 323 | .BR open () |
fea681da | 324 | can open device special files, but |
1c1e15ed | 325 | .BR creat () |
e9496f74 | 326 | cannot create them; use |
fea681da MK |
327 | .BR mknod (2) |
328 | instead. | |
329 | .LP | |
e366dbc4 | 330 | On NFS file systems with UID mapping enabled, \fBopen\fP() may |
1c1e15ed MK |
331 | return a file descriptor but e.g. \fBread\fP(2) requests are denied |
332 | with \fBEACCES\fP. | |
e366dbc4 | 333 | This is because the client performs \fBopen\fP() by checking the |
1c1e15ed MK |
334 | permissions, but UID mapping is performed by the server upon |
335 | read and write requests. | |
fea681da | 336 | |
310b7919 MK |
337 | If the file is newly created, its st_atime, st_ctime, st_mtime fields |
338 | (respectively, time of last access, time of last status change, and | |
339 | time of last modification; see | |
340 | .BR stat (2)) | |
341 | are set | |
342 | to the current time, and so are the st_ctime and st_mtime fields of the | |
fea681da MK |
343 | parent directory. |
344 | Otherwise, if the file is modified because of the O_TRUNC flag, | |
310b7919 | 345 | its st_ctime and st_mtime fields are set to the current time. |
fea681da MK |
346 | .SH ERRORS |
347 | .TP | |
348 | .B EACCES | |
349 | The requested access to the file is not allowed, or search permission | |
350 | is denied for one of the directories in the path prefix of | |
351 | .IR pathname , | |
352 | or the file did not exist yet and write access to the parent directory | |
353 | is not allowed. | |
354 | (See also | |
355 | .BR path_resolution (2).) | |
356 | .TP | |
357 | .B EEXIST | |
358 | .I pathname | |
359 | already exists and | |
360 | .BR O_CREAT " and " O_EXCL | |
361 | were used. | |
362 | .TP | |
363 | .B EFAULT | |
364 | .IR pathname " points outside your accessible address space." | |
365 | .TP | |
366 | .B EISDIR | |
367 | .I pathname | |
368 | refers to a directory and the access requested involved writing | |
369 | (that is, | |
370 | .B O_WRONLY | |
371 | or | |
372 | .B O_RDWR | |
373 | is set). | |
374 | .TP | |
375 | .B ELOOP | |
376 | Too many symbolic links were encountered in resolving | |
377 | .IR pathname , | |
378 | or \fBO_NOFOLLOW\fR was specified but | |
379 | .I pathname | |
380 | was a symbolic link. | |
381 | .TP | |
382 | .B EMFILE | |
383 | The process already has the maximum number of files open. | |
384 | .TP | |
385 | .B ENAMETOOLONG | |
386 | .IR pathname " was too long." | |
387 | .TP | |
388 | .B ENFILE | |
389 | The system limit on the total number of open files has been reached. | |
390 | .TP | |
391 | .B ENODEV | |
392 | .I pathname | |
393 | refers to a device special file and no corresponding device exists. | |
e9496f74 | 394 | (This is a Linux kernel bug; in this situation ENXIO must be returned.) |
fea681da MK |
395 | .TP |
396 | .B ENOENT | |
397 | O_CREAT is not set and the named file does not exist. | |
398 | Or, a directory component in | |
399 | .I pathname | |
400 | does not exist or is a dangling symbolic link. | |
401 | .TP | |
402 | .B ENOMEM | |
403 | Insufficient kernel memory was available. | |
404 | .TP | |
405 | .B ENOSPC | |
406 | .I pathname | |
407 | was to be created but the device containing | |
408 | .I pathname | |
409 | has no room for the new file. | |
410 | .TP | |
411 | .B ENOTDIR | |
412 | A component used as a directory in | |
413 | .I pathname | |
414 | is not, in fact, a directory, or \fBO_DIRECTORY\fR was specified and | |
415 | .I pathname | |
416 | was not a directory. | |
417 | .TP | |
418 | .B ENXIO | |
419 | O_NONBLOCK | O_WRONLY is set, the named file is a FIFO and | |
420 | no process has the file open for reading. | |
421 | Or, the file is a device special file and no corresponding device exists. | |
422 | .TP | |
423 | .B EOVERFLOW | |
424 | .I pathname | |
e9496f74 | 425 | refers to a regular file, too large to be opened; see O_LARGEFILE above. |
fea681da | 426 | .TP |
1c1e15ed MK |
427 | .B EPERM |
428 | The | |
429 | .B O_NOATIME | |
430 | flag was specified, but the effective user ID of the caller | |
431 | .\" Strictly speaking, it's the file system UID... (MTK) | |
432 | did not match the owner of the file and the caller was not privileged | |
433 | .RB ( CAP_FOWNER ). | |
434 | .TP | |
fea681da MK |
435 | .B EROFS |
436 | .I pathname | |
437 | refers to a file on a read-only filesystem and write access was | |
438 | requested. | |
439 | .TP | |
440 | .B ETXTBSY | |
441 | .I pathname | |
442 | refers to an executable image which is currently being executed and | |
443 | write access was requested. | |
444 | .SH NOTE | |
445 | Under Linux, the O_NONBLOCK flag indicates that one wants to open | |
446 | but does not necessarily have the intention to read or write. | |
447 | This is typically used to open devices in order to get a file descriptor | |
448 | for use with | |
449 | .BR ioctl (2). | |
450 | .SH "CONFORMING TO" | |
b14d4aa5 | 451 | SVr4, SVID, POSIX, X/OPEN, 4.3BSD. |
fea681da | 452 | The |
1c1e15ed MK |
453 | .BR O_NOATIME , |
454 | .BR O_NOFOLLOW , | |
fea681da MK |
455 | and |
456 | .B O_DIRECTORY | |
457 | flags are Linux-specific. | |
458 | One may have to define the | |
459 | .B _GNU_SOURCE | |
460 | macro to get their definitions. | |
461 | .LP | |
462 | The (undefined) effect of | |
463 | .B O_RDONLY | O_TRUNC | |
1f6ceb40 | 464 | varies among implementations. On many systems the file is actually |
fea681da MK |
465 | truncated. |
466 | .\" Linux 2.0, 2.5: truncate | |
467 | .\" Solaris 5.7, 5.8: truncate | |
468 | .\" Irix 6.5: truncate | |
469 | .\" Tru64 5.1B: truncate | |
470 | .\" HP-UX 11.22: truncate | |
471 | .\" FreeBSD 4.7: truncate | |
472 | .LP | |
473 | The | |
474 | .B O_DIRECT | |
475 | flag was introduced in SGI IRIX, where it has alignment restrictions | |
476 | similar to those of Linux 2.4. IRIX has also a fcntl(2) call to | |
477 | query appropriate alignments, and sizes. FreeBSD 4.x introduced | |
478 | a flag of same name, but without alignment restrictions. | |
479 | Support was added under Linux in kernel version 2.4.10. | |
480 | Older Linux kernels simply ignore this flag. | |
1f6ceb40 MK |
481 | One may have to define the |
482 | .B _GNU_SOURCE | |
483 | macro to get its definition. | |
fea681da MK |
484 | .SH BUGS |
485 | "The thing that has always disturbed me about O_DIRECT is that the whole | |
486 | interface is just stupid, and was probably designed by a deranged monkey | |
e9496f74 | 487 | on some serious mind-controlling substances." \(em Linus |
fea681da MK |
488 | .SH RESTRICTIONS |
489 | There are many infelicities in the protocol underlying NFS, affecting | |
490 | amongst others | |
491 | .BR O_SYNC " and " O_NDELAY . | |
492 | ||
493 | POSIX provides for three different variants of synchronised I/O, | |
494 | corresponding to the flags \fBO_SYNC\fR, \fBO_DSYNC\fR and | |
495 | \fBO_RSYNC\fR. Currently (2.1.130) these are all synonymous under Linux. | |
496 | .SH "SEE ALSO" | |
497 | .BR close (2), | |
e366dbc4 | 498 | .BR dup (2), |
fea681da MK |
499 | .BR fcntl (2), |
500 | .BR link (2), | |
1f6ceb40 | 501 | .BR lseek (2), |
fea681da MK |
502 | .BR mknod (2), |
503 | .BR mount (2), | |
e366dbc4 | 504 | .BR mmap (2), |
fea681da MK |
505 | .BR path_resolution (2), |
506 | .BR read (2), | |
507 | .BR socket (2), | |
508 | .BR stat (2), | |
509 | .BR umask (2), | |
510 | .BR unlink (2), | |
511 | .BR write (2), | |
512 | .BR fopen (3), | |
513 | .BR fifo (4) |