-
Notifications
You must be signed in to change notification settings - Fork 0
/
openat.html
1883 lines (1428 loc) · 59 KB
/
openat.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:27:14 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>OPEN</title>
</head>
<body>
<h1 align="center">OPEN</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#VERSIONS">VERSIONS</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#BUGS">BUGS</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">open, openat,
creat - open and possibly create a file</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<sys/types.h> <br>
#include <sys/stat.h> <br>
#include <fcntl.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>int
open(const char *</b><i>pathname</i><b>, int</b>
<i>flags</i><b>); <br>
int open(const char *</b><i>pathname</i><b>, int</b>
<i>flags</i><b>, mode_t</b> <i>mode</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>int
creat(const char *</b><i>pathname</i><b>, mode_t</b>
<i>mode</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>int
openat(int</b> <i>dirfd</i><b>, const char
*</b><i>pathname</i><b>, int</b> <i>flags</i><b>); <br>
int openat(int</b> <i>dirfd</i><b>, const char
*</b><i>pathname</i><b>, int</b> <i>flags</i><b>, mode_t</b>
<i>mode</i><b>);</b></p>
<p style="margin-left:5%; margin-top: 1em">Feature Test
Macro Requirements for glibc (see
<b>feature_test_macros</b>(7)):</p>
<p style="margin-left:11%; margin-top: 1em"><b>openat</b>():</p>
<p style="margin-left:17%;">Since glibc 2.10:</p>
<p style="margin-left:23%;">_POSIX_C_SOURCE >= 200809L</p>
<p style="margin-left:17%;">Before glibc 2.10:</p>
<p style="margin-left:23%;">_ATFILE_SOURCE</p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
<b>open</b>() system call opens the file specified by
<i>pathname</i>. If the specified file does not exist, it
may optionally (if <b>O_CREAT</b> is specified in
<i>flags</i>) be created by <b>open</b>().</p>
<p style="margin-left:11%; margin-top: 1em">The return
value of <b>open</b>() is a file descriptor, a small,
nonnegative integer that is used in subsequent system calls
(<b>read</b>(2), <b>write</b>(2), <b>lseek</b>(2),
<b>fcntl</b>(2), etc.) to refer to the open file. The file
descriptor returned by a successful call will be the
lowest-numbered file descriptor not currently open for the
process.</p>
<p style="margin-left:11%; margin-top: 1em">By default, the
new file descriptor is set to remain open across an
<b>execve</b>(2) (i.e., the <b>FD_CLOEXEC</b> file
descriptor flag described in <b>fcntl</b>(2) is initially
disabled); the <b>O_CLOEXEC</b> flag, described below, can
be used to change this default. The file offset is set to
the beginning of the file (see <b>lseek</b>(2)).</p>
<p style="margin-left:11%; margin-top: 1em">A call to
<b>open</b>() creates a new <i>open file description</i>, an
entry in the system-wide table of open files. The open file
description records the file offset and the file status
flags (see below). A file descriptor is a reference to an
open file description; this reference is unaffected if
<i>pathname</i> is subsequently removed or modified to refer
to a different file. For further details on open file
descriptions, see NOTES.</p>
<p style="margin-left:11%; margin-top: 1em">The argument
<i>flags</i> must include one of the following <i>access
modes</i>: <b>O_RDONLY</b>, <b>O_WRONLY</b>, or
<b>O_RDWR</b>. These request opening the file read-only,
write-only, or read/write, respectively.</p>
<p style="margin-left:11%; margin-top: 1em">In addition,
zero or more file creation flags and file status flags can
be bitwise-<i>or</i>’d in <i>flags</i>. The <i>file
creation flags</i> are <b>O_CLOEXEC</b>, <b>O_CREAT</b>,
<b>O_DIRECTORY</b>, <b>O_EXCL</b>, <b>O_NOCTTY</b>,
<b>O_NOFOLLOW</b>, <b>O_TMPFILE</b>, and <b>O_TRUNC</b>. The
<i>file status flags</i> are all of the remaining flags
listed below. The distinction between these two groups of
flags is that the file creation flags affect the semantics
of the open operation itself, while the file status flags
affect the semantics of subsequent I/O operations. The file
status flags can be retrieved and (in some cases) modified;
see <b>fcntl</b>(2) for details.</p>
<p style="margin-left:11%; margin-top: 1em">The full list
of file creation flags and file status flags is as follows:
<b><br>
O_APPEND</b></p>
<p style="margin-left:22%;">The file is opened in append
mode. Before each <b>write</b>(2), the file offset is
positioned at the end of the file, as if with
<b>lseek</b>(2). The modification of the file offset and the
write operation are performed as a single atomic step.</p>
<p style="margin-left:22%; margin-top: 1em"><b>O_APPEND</b>
may lead to corrupted files on NFS filesystems if more than
one process appends data to a file at once. This is because
NFS does not support appending to a file, so the client
kernel has to simulate it, which can’t be done without
a race condition.</p>
<p style="margin-left:11%;"><b>O_ASYNC</b></p>
<p style="margin-left:22%;">Enable signal-driven I/O:
generate a signal (<b>SIGIO</b> by default, but this can be
changed via <b>fcntl</b>(2)) when input or output becomes
possible on this file descriptor. This feature is available
only for terminals, pseudoterminals, sockets, and (since
Linux 2.6) pipes and FIFOs. See <b>fcntl</b>(2) for further
details. See also BUGS, below.</p>
<p style="margin-left:11%;"><b>O_CLOEXEC</b> (since Linux
2.6.23)</p>
<p style="margin-left:22%;">Enable the close-on-exec flag
for the new file descriptor. Specifying this flag permits a
program to avoid additional <b>fcntl</b>(2) <b>F_SETFD</b>
operations to set the <b>FD_CLOEXEC</b> flag.</p>
<p style="margin-left:22%; margin-top: 1em">Note that the
use of this flag is essential in some multithreaded
programs, because using a separate <b>fcntl</b>(2)
<b>F_SETFD</b> operation to set the <b>FD_CLOEXEC</b> flag
does not suffice to avoid race conditions where one thread
opens a file descriptor and attempts to set its
close-on-exec flag using <b>fcntl</b>(2) at the same time as
another thread does a <b>fork</b>(2) plus <b>execve</b>(2).
Depending on the order of execution, the race may lead to
the file descriptor returned by <b>open</b>() being
unintentionally leaked to the program executed by the child
process created by <b>fork</b>(2). (This kind of race is in
principle possible for any system call that creates a file
descriptor whose close-on-exec flag should be set, and
various other Linux system calls provide an equivalent of
the <b>O_CLOEXEC</b> flag to deal with this problem.)</p>
<p style="margin-left:11%;"><b>O_CREAT</b></p>
<p style="margin-left:22%;">If <i>pathname</i> does not
exist, create it as a regular file.</p>
<p style="margin-left:22%; margin-top: 1em">The owner (user
ID) of the new file is set to the effective user ID of the
process.</p>
<p style="margin-left:22%; margin-top: 1em">The group
ownership (group ID) of the new file is set either to the
effective group ID of the process (System V semantics) or to
the group ID of the parent directory (BSD semantics). On
Linux, the behavior depends on whether the set-group-ID mode
bit is set on the parent directory: if that bit is set, then
BSD semantics apply; otherwise, System V semantics apply.
For some filesystems, the behavior also depends on the
<i>bsdgroups</i> and <i>sysvgroups</i> mount options
described in <b>mount</b>(8)).</p>
<p style="margin-left:22%; margin-top: 1em">The <i>mode</i>
argument specifies the file mode bits be applied when a new
file is created. This argument must be supplied when
<b>O_CREAT</b> or <b>O_TMPFILE</b> is specified in
<i>flags</i>; if neither <b>O_CREAT</b> nor <b>O_TMPFILE</b>
is specified, then <i>mode</i> is ignored. The effective
mode is modified by the process’s <i>umask</i> in the
usual way: in the absence of a default ACL, the mode of the
created file is <i>(mode & ~umask)</i>. Note
that this mode applies only to future accesses of the newly
created file; the <b>open</b>() call that creates a
read-only file may well return a read/write file
descriptor.</p>
<p style="margin-left:22%; margin-top: 1em">The following
symbolic constants are provided for <i>mode</i>:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IRWXU</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00700 user (file owner) has read, write, and execute
permission</p> </td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IRUSR</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00400 user has read permission</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IWUSR</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00200 user has write permission</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IXUSR</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00100 user has execute permission</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IRWXG</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00070 group has read, write, and execute permission</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IRGRP</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00040 group has read permission</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IWGRP</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00020 group has write permission</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IXGRP</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00010 group has execute permission</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IRWXO</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00007 others have read, write, and execute
permission</p> </td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IROTH</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00004 others have read permission</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IWOTH</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00002 others have write permission</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_IXOTH</b></p></td>
<td width="3%"></td>
<td width="65%">
<p>00001 others have execute permission</p></td></tr>
</table>
<p style="margin-left:22%; margin-top: 1em">According to
POSIX, the effect when other bits are set in <i>mode</i> is
unspecified. On Linux, the following bits are also honored
in <i>mode</i>:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p style="margin-top: 1em"><b>S_ISUID</b></p></td>
<td width="3%"></td>
<td width="62%">
<p style="margin-top: 1em">0004000 set-user-ID bit</p></td>
<td width="3%">
</td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_ISGID</b></p></td>
<td width="3%"></td>
<td width="62%">
<p>0002000 set-group-ID bit (see <b>inode</b>(7)).</p></td>
<td width="3%">
</td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="10%">
<p><b>S_ISVTX</b></p></td>
<td width="3%"></td>
<td width="62%">
<p>0001000 sticky bit (see <b>inode</b>(7)).</p></td>
<td width="3%">
</td></tr>
</table>
<p style="margin-left:11%;"><b>O_DIRECT</b> (since Linux
2.4.10)</p>
<p style="margin-left:22%;">Try to minimize cache effects
of the I/O to and from this file. In general this will
degrade performance, but it is useful in special situations,
such as when applications do their own caching. File I/O is
done directly to/from user-space buffers. The
<b>O_DIRECT</b> flag on its own makes an effort to transfer
data synchronously, but does not give the guarantees of the
<b>O_SYNC</b> flag that data and necessary metadata are
transferred. To guarantee synchronous I/O, <b>O_SYNC</b>
must be used in addition to <b>O_DIRECT</b>. See NOTES below
for further discussion.</p>
<p style="margin-left:22%; margin-top: 1em">A semantically
similar (but deprecated) interface for block devices is
described in <b>raw</b>(8).</p>
<p style="margin-left:11%;"><b>O_DIRECTORY</b></p>
<p style="margin-left:22%;">If <i>pathname</i> is not a
directory, cause the open to fail. This flag was added in
kernel version 2.1.126, to avoid denial-of-service problems
if <b>opendir</b>(3) is called on a FIFO or tape device.</p>
<p style="margin-left:11%;"><b>O_DSYNC</b></p>
<p style="margin-left:22%;">Write operations on the file
will complete according to the requirements of synchronized
I/O <i>data</i> integrity completion.</p>
<p style="margin-left:22%; margin-top: 1em">By the time
<b>write</b>(2) (and similar) return, the output data has
been transferred to the underlying hardware, along with any
file metadata that would be required to retrieve that data
(i.e., as though each <b>write</b>(2) was followed by a call
to <b>fdatasync</b>(2)). <i>See NOTES below</i>.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>O_EXCL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>Ensure that this call creates the file: if this flag is
specified in conjunction with <b>O_CREAT</b>, and
<i>pathname</i> already exists, then <b>open</b>() fails
with the error <b>EEXIST</b>.</p></td></tr>
</table>
<p style="margin-left:22%; margin-top: 1em">When these two
flags are specified, symbolic links are not followed: if
<i>pathname</i> is a symbolic link, then <b>open</b>() fails
regardless of where the symbolic link points.</p>
<p style="margin-left:22%; margin-top: 1em">In general, the
behavior of <b>O_EXCL</b> is undefined if it is used without
<b>O_CREAT</b>. There is one exception: on Linux 2.6 and
later, <b>O_EXCL</b> can be used without <b>O_CREAT</b> if
<i>pathname</i> refers to a block device. If the block
device is in use by the system (e.g., mounted),
<b>open</b>() fails with the error <b>EBUSY</b>.</p>
<p style="margin-left:22%; margin-top: 1em">On NFS,
<b>O_EXCL</b> is supported only when using NFSv3 or later on
kernel 2.6 or later. In NFS environments where <b>O_EXCL</b>
support is not provided, programs that rely on it for
performing locking tasks will contain a race condition.
Portable programs that want to perform atomic file locking
using a lockfile, and need to avoid reliance on NFS support
for <b>O_EXCL</b>, can create a unique file on the same
filesystem (e.g., incorporating hostname and PID), and use
<b>link</b>(2) to make a link to the lockfile. If
<b>link</b>(2) returns 0, the lock is successful. Otherwise,
use <b>stat</b>(2) on the unique file to check if its link
count has increased to 2, in which case the lock is also
successful.</p>
<p style="margin-left:11%;"><b>O_LARGEFILE</b></p>
<p style="margin-left:22%;">(LFS) Allow files whose sizes
cannot be represented in an <i>off_t</i> (but can be
represented in an <i>off64_t</i>) to be opened. The
<b>_LARGEFILE64_SOURCE</b> macro must be defined (before
including <i>any</i> header files) in order to obtain this
definition. Setting the <b>_FILE_OFFSET_BITS</b> feature
test macro to 64 (rather than using <b>O_LARGEFILE</b>) is
the preferred method of accessing large files on 32-bit
systems (see <b>feature_test_macros</b>(7)).</p>
<p style="margin-left:11%;"><b>O_NOATIME</b> (since Linux
2.6.8)</p>
<p style="margin-left:22%;">Do not update the file last
access time (<i>st_atime</i> in the inode) when the file is
<b>read</b>(2).</p>
<p style="margin-left:22%; margin-top: 1em">This flag can
be employed only if one of the following conditions is
true:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p>The effective UID of the process matches the owner UID
of the file.</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p>The calling process has the <b>CAP_FOWNER</b> capability
in its user namespace and the owner UID of the file has a
mapping in the namespace.</p></td></tr>
</table>
<p style="margin-left:22%; margin-top: 1em">This flag is
intended for use by indexing or backup programs, where its
use can significantly reduce the amount of disk activity.
This flag may not be effective on all filesystems. One
example is NFS, where the server maintains the access
time.</p>
<p style="margin-left:11%;"><b>O_NOCTTY</b></p>
<p style="margin-left:22%;">If <i>pathname</i> refers to a
terminal device—see <b>tty</b>(4)—it will not
become the process’s controlling terminal even if the
process does not have one.</p>
<p style="margin-left:11%;"><b>O_NOFOLLOW</b></p>
<p style="margin-left:22%;">If <i>pathname</i> is a
symbolic link, then the open fails, with the error
<b>ELOOP</b>. Symbolic links in earlier components of the
pathname will still be followed. (Note that the <b>ELOOP</b>
error that can occur in this case is indistinguishable from
the case where an open fails because there are too many
symbolic links found while resolving components in the
prefix part of the pathname.)</p>
<p style="margin-left:22%; margin-top: 1em">This flag is a
FreeBSD extension, which was added to Linux in version
2.1.126, and has subsequently been standardized in
POSIX.1-2008.</p>
<p style="margin-left:22%; margin-top: 1em">See also
<b>O_PATH</b> below.</p>
<p style="margin-left:11%;"><b>O_NONBLOCK</b> or
<b>O_NDELAY</b></p>
<p style="margin-left:22%;">When possible, the file is
opened in nonblocking mode. Neither the <b>open</b>() nor
any subsequent I/O operations on the file descriptor which
is returned will cause the calling process to wait.</p>
<p style="margin-left:22%; margin-top: 1em">Note that ithe
setting of this flag has no effect on the operation of
<b>poll</b>(2), <b>select</b>(2), <b>epoll</b>(7), and
similar, since those interfaces merely inform the caller
about whether a file descriptor is "ready",
meaning that an I/O operation performed on the file
descriptor with the <b>O_NONBLOCK</b> flag <i>clear</i>
would not block.</p>
<p style="margin-left:22%; margin-top: 1em">Note that this
flag has no effect for regular files and block devices; that
is, I/O operations will (briefly) block when device activity
is required, regardless of whether <b>O_NONBLOCK</b> is set.
Since <b>O_NONBLOCK</b> semantics might eventually be
implemented, applications should not depend upon blocking
behavior when specifying this flag for regular files and
block devices.</p>
<p style="margin-left:22%; margin-top: 1em">For the
handling of FIFOs (named pipes), see also <b>fifo</b>(7).
For a discussion of the effect of <b>O_NONBLOCK</b> in
conjunction with mandatory file locks and with file leases,
see <b>fcntl</b>(2).</p>
<p style="margin-left:11%;"><b>O_PATH</b> (since Linux
2.6.39)</p>
<p style="margin-left:22%;">Obtain a file descriptor that
can be used for two purposes: to indicate a location in the
filesystem tree and to perform operations that act purely at
the file descriptor level. The file itself is not opened,
and other file operations (e.g., <b>read</b>(2),
<b>write</b>(2), <b>fchmod</b>(2), <b>fchown</b>(2),
<b>fgetxattr</b>(2), <b>ioctl</b>(2), <b>mmap</b>(2)) fail
with the error <b>EBADF</b>.</p>
<p style="margin-left:22%; margin-top: 1em">The following
operations <i>can</i> be performed on the resulting file
descriptor:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p><b>close</b>(2).</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p><b>fchdir</b>(2), if the file descriptor refers to a
directory (since Linux 3.5).</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p><b>fstat</b>(2) (since Linux 3.6).</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p><b>fstatfs</b>(2) (since Linux 3.12).</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p>Duplicating the file descriptor (<b>dup</b>(2),
<b>fcntl</b>(2) <b>F_DUPFD</b>, etc.).</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p>Getting and setting file descriptor flags
(<b>fcntl</b>(2) <b>F_GETFD</b> and <b>F_SETFD</b>).</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p>Retrieving open file status flags using the
<b>fcntl</b>(2) <b>F_GETFL</b> operation: the returned flags
will include the bit <b>O_PATH</b>.</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p>Passing the file descriptor as the <i>dirfd</i> argument
of <b>openat</b>() and the other "*at()" system
calls. This includes <b>linkat</b>(2) with
<b>AT_EMPTY_PATH</b> (or via procfs using
<b>AT_SYMLINK_FOLLOW</b>) even if the file is not a
directory.</p> </td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p>Passing the file descriptor to another process via a
UNIX domain socket (see <b>SCM_RIGHTS</b> in
<b>unix</b>(7)).</p> </td></tr>
</table>
<p style="margin-left:22%; margin-top: 1em">When
<b>O_PATH</b> is specified in <i>flags</i>, flag bits other
than <b>O_CLOEXEC</b>, <b>O_DIRECTORY</b>, and
<b>O_NOFOLLOW</b> are ignored.</p>
<p style="margin-left:22%; margin-top: 1em">Opening a file
or directory with the <b>O_PATH</b> flag requires no
permissions on the object itself (but does require execute
permission on the directories in the path prefix). Depending
on the subsequent operation, a check for suitable file
permissions may be performed (e.g., <b>fchdir</b>(2)
requires execute permission on the directory referred to by
its file descriptor argument). By contrast, obtaining a
reference to a filesystem object by opening it with the
<b>O_RDONLY</b> flag requires that the caller have read
permission on the object, even when the subsequent operation
(e.g., <b>fchdir</b>(2), <b>fstat</b>(2)) does not require
read permission on the object.</p>
<p style="margin-left:22%; margin-top: 1em">If
<i>pathname</i> is a symbolic link and the <b>O_NOFOLLOW</b>
flag is also specified, then the call returns a file
descriptor referring to the symbolic link. This file
descriptor can be used as the <i>dirfd</i> argument in calls
to <b>fchownat</b>(2), <b>fstatat</b>(2), <b>linkat</b>(2),
and <b>readlinkat</b>(2) with an empty pathname to have the
calls operate on the symbolic link.</p>
<p style="margin-left:22%; margin-top: 1em">If
<i>pathname</i> refers to an automount point that has not
yet been triggered, so no other filesystem is mounted on it,
then the call returns a file descriptor referring to the
automount directory without triggering a mount.
<b>fstatfs</b>(2) can then be used to determine if it is, in
fact, an untriggered automount point (<b>.f_type ==
AUTOFS_SUPER_MAGIC</b>).</p>
<p style="margin-left:22%; margin-top: 1em">One use of
<b>O_PATH</b> for regular files is to provide the equivalent
of POSIX.1’s <b>O_EXEC</b> functionality. This permits
us to open a file for which we have execute permission but
not read permission, and then execute that file, with steps
something like the following:</p>
<p style="margin-left:28%; margin-top: 1em">char
buf[PATH_MAX]; <br>
fd = open("some_prog", O_PATH); <br>
snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd);
<br>
execl(buf, "some_prog", (char *) NULL);</p>
<p style="margin-left:22%; margin-top: 1em">An
<b>O_PATH</b> file descriptor can also be passed as the
argument of <b>fexecve</b>(3).</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p style="margin-top: 1em"><b>O_SYNC</b></p></td>
<td width="2%"></td>
<td width="78%">
<p style="margin-top: 1em">Write operations on the file
will complete according to the requirements of synchronized
I/O <i>file</i> integrity completion (by contrast with the
synchronized I/O <i>data</i> integrity completion provided
by <b>O_DSYNC</b>.)</p></td></tr>
</table>
<p style="margin-left:22%; margin-top: 1em">By the time
<b>write</b>(2) (or similar) returns, the output data and
associated file metadata have been transferred to the
underlying hardware (i.e., as though each <b>write</b>(2)
was followed by a call to <b>fsync</b>(2)). <i>See NOTES
below</i>.</p>
<p style="margin-left:11%;"><b>O_TMPFILE</b> (since Linux
3.11)</p>
<p style="margin-left:22%;">Create an unnamed temporary
regular file. The <i>pathname</i> argument specifies a
directory; an unnamed inode will be created in that
directory’s filesystem. Anything written to the
resulting file will be lost when the last file descriptor is
closed, unless the file is given a name.</p>
<p style="margin-left:22%; margin-top: 1em"><b>O_TMPFILE</b>
must be specified with one of <b>O_RDWR</b> or
<b>O_WRONLY</b> and, optionally, <b>O_EXCL</b>. If
<b>O_EXCL</b> is not specified, then <b>linkat</b>(2) can be
used to link the temporary file into the filesystem, making
it permanent, using code like the following:</p>
<p style="margin-left:28%; margin-top: 1em">char
path[PATH_MAX]; <br>
fd = open("/path/to/dir", O_TMPFILE | O_RDWR, <br>
S_IRUSR | S_IWUSR);</p>
<p style="margin-left:28%; margin-top: 1em">/* File I/O on
’fd’... */</p>
<p style="margin-left:28%; margin-top: 1em">snprintf(path,
PATH_MAX, "/proc/self/fd/%d", fd); <br>
linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
<br>
AT_SYMLINK_FOLLOW);</p>
<p style="margin-left:22%; margin-top: 1em">In this case,
the <b>open</b>() <i>mode</i> argument determines the file
permission mode, as with <b>O_CREAT</b>.</p>
<p style="margin-left:22%; margin-top: 1em">Specifying
<b>O_EXCL</b> in conjunction with <b>O_TMPFILE</b> prevents
a temporary file from being linked into the filesystem in
the above manner. (Note that the meaning of <b>O_EXCL</b> in
this case is different from the meaning of <b>O_EXCL</b>
otherwise.)</p>
<p style="margin-left:22%; margin-top: 1em">There are two
main use cases for <b>O_TMPFILE</b>:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p>Improved <b>tmpfile</b>(3) functionality: race-free
creation of temporary files that (1) are automatically
deleted when closed; (2) can never be reached via any
pathname; (3) are not subject to symlink attacks; and (4) do
not require the caller to devise unique names.</p></td></tr>
<tr valign="top" align="left">
<td width="22%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="74%">
<p>Creating a file that is initially invisible, which is
then populated with data and adjusted to have appropriate
filesystem attributes (<b>fchown</b>(2), <b>fchmod</b>(2),
<b>fsetxattr</b>(2), etc.) before being atomically linked
into the filesystem in a fully formed state (using
<b>linkat</b>(2) as described above).</p></td></tr>
</table>
<p style="margin-left:22%; margin-top: 1em"><b>O_TMPFILE</b>
requires support by the underlying filesystem; only a subset
of Linux filesystems provide that support. In the initial
implementation, support was provided in the ext2, ext3,
ext4, UDF, Minix, and shmem filesystems. Support for other
filesystems has subsequently been added as follows: XFS
(Linux 3.15); Btrfs (Linux 3.16); F2FS (Linux 3.16); and
ubifs (Linux 4.9)</p>
<p style="margin-left:11%;"><b>O_TRUNC</b></p>
<p style="margin-left:22%;">If the file already exists and
is a regular file and the access mode allows writing (i.e.,
is <b>O_RDWR</b> or <b>O_WRONLY</b>) it will be truncated to
length 0. If the file is a FIFO or terminal device file, the
<b>O_TRUNC</b> flag is ignored. Otherwise, the effect of
<b>O_TRUNC</b> is unspecified.</p>
<p style="margin-left:11%; margin-top: 1em"><b>creat()</b>
<br>
A call to <b>creat</b>() is equivalent to calling
<b>open</b>() with <i>flags</i> equal to
<b>O_CREAT|O_WRONLY|O_TRUNC</b>.</p>
<p style="margin-left:11%; margin-top: 1em"><b>openat()</b>
<br>
The <b>openat</b>() system call operates in exactly the same
way as <b>open</b>(), except for the differences described
here.</p>
<p style="margin-left:11%; margin-top: 1em">If the pathname
given in <i>pathname</i> is relative, then it is interpreted
relative to the directory referred to by the file descriptor
<i>dirfd</i> (rather than relative to the current working
directory of the calling process, as is done by
<b>open</b>() for a relative pathname).</p>
<p style="margin-left:11%; margin-top: 1em">If
<i>pathname</i> is relative and <i>dirfd</i> is the special
value <b>AT_FDCWD</b>, then <i>pathname</i> is interpreted
relative to the current working directory of the calling
process (like <b>open</b>()).</p>
<p style="margin-left:11%; margin-top: 1em">If
<i>pathname</i> is absolute, then <i>dirfd</i> is
ignored.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>open</b>(),
<b>openat</b>(), and <b>creat</b>() return the new file
descriptor, or -1 if an error occurred (in which case,
<i>errno</i> is set appropriately).</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>open</b>(),
<b>openat</b>(), and <b>creat</b>() can fail with the
following errors:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EACCES</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The requested access to the file is not allowed, or
search permission is denied for one of the directories in