| blob | fa75967763514fb42cdb5f46d1d46cb1df64db0a |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
45 .\"
46 .TH FCNTL.H 3HEAD "April 9, 2016"
47 .SH NAME
48 fcntl.h, fcntl \- file control options
49 .SH SYNOPSIS
50 .LP
51 .nf
52 #include <fcntl.h>
53 .fi
55 .SH DESCRIPTION
56 .LP
57 The \fB<fcntl.h>\fR header defines the following requests and arguments for use
58 by the functions \fBfcntl\fR(2), \fBopen\fR(2), and \fBopenat\fR(2).
59 .sp
60 .LP
61 Values for \fIcmd\fR used by \fBfcntl()\fR (the following values are unique):
62 .sp
63 .ne 2
64 .na
65 \fB\fBF_DUPFD\fR\fR
66 .ad
67 .RS 15n
68 Duplicate file descriptor.
69 .RE
71 .sp
72 .ne 2
73 .na
74 \fB\fBF_DUP2FD\fR\fR
75 .ad
76 .RS 15n
77 Similar to \fBF_DUPFD\fR, but always returns \fIarg\fR.
78 .RE
80 .sp
81 .ne 2
82 .na
83 \fB\fBF_GETFD\fR\fR
84 .ad
85 .RS 15n
86 Get file descriptor flags.
87 .RE
89 .sp
90 .ne 2
91 .na
92 \fB\fBF_SETFD\fR\fR
93 .ad
94 .RS 15n
95 Set file descriptor flags.
96 .RE
98 .sp
99 .ne 2
100 .na
101 \fB\fBF_GETFL\fR\fR
102 .ad
103 .RS 15n
104 Get file status flags.
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fB\fBF_SETFL\fR\fR
111 .ad
112 .RS 15n
113 Set file status flags.
114 .RE
116 .sp
117 .ne 2
118 .na
119 \fB\fBF_GETOWN\fR\fR
120 .ad
121 .RS 15n
122 Get process or process group \fBID\fR to receive \fBSIGURG\fR signals.
123 .RE
125 .sp
126 .ne 2
127 .na
128 \fB\fBF_SETOWN\fR\fR
129 .ad
130 .RS 15n
131 Set process or process group \fBID\fR to receive \fBSIGURG\fR signals.
132 .RE
134 .sp
135 .ne 2
136 .na
137 \fB\fBF_FREESP\fR\fR
138 .ad
139 .RS 15n
140 Free storage space associated with a section of the ordinary file \fIfildes\fR.
141 .RE
143 .sp
144 .ne 2
145 .na
146 \fB\fBF_ALLOCSP\fR\fR
147 .ad
148 .RS 15n
149 Allocate space for a section of the ordinary file \fIfildes\fR.
150 .RE
152 .sp
153 .ne 2
154 .na
155 \fB\fBF_ALLOCSP64\fR\fR
156 .ad
157 .RS 15n
158 Equivalent to \fBF_ALLOCSP\fR, but takes a \fBstruct flock64\fR argument rather
159 than a \fBstruct flock\fR argument.
160 .RE
162 .sp
163 .ne 2
164 .na
165 \fB\fBF_GETLK\fR\fR
166 .ad
167 .RS 15n
168 Get record locking information.
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fB\fBF_GETLK64\fR\fR
175 .ad
176 .RS 15n
177 Equivalent to \fBF_GETLK\fR, but takes a \fBstruct flock64\fR argument rather
178 than a \fBstruct flock\fR argument.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fBF_SETLK\fR\fR
185 .ad
186 .RS 15n
187 Set record locking information.
188 .RE
190 .sp
191 .ne 2
192 .na
193 \fB\fBF_SETLK64\fR\fR
194 .ad
195 .RS 15n
196 Equivalent to \fBF_SETLK\fR, but takes a \fBstruct flock64\fR argument rather
197 than a \fBstruct flock\fR argument.
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fBF_SETLKW\fR\fR
204 .ad
205 .RS 15n
206 Set record locking information; wait if blocked.
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fBF_SETLKW64\fR\fR
213 .ad
214 .RS 15n
215 Equivalent to \fBF_SETLKW\fR, but takes a \fBstruct flock64\fR argument rather
216 than a \fBstruct flock\fR argument.
217 .RE
219 .sp
220 .ne 2
221 .na
222 \fB\fBF_SHARE\fR\fR
223 .ad
224 .RS 15n
225 Set share reservation.
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fBF_UNSHARE\fR\fR
232 .ad
233 .RS 15n
234 Remove share reservation.
235 .RE
237 .sp
238 .LP
239 File descriptor flags used for \fBfcntl()\fR:
240 .sp
241 .ne 2
242 .na
243 \fB\fBFD_CLOEXEC\fR\fR
244 .ad
245 .RS 14n
246 Close the file descriptor upon execution of an \fBexec\fR function (see
247 \fBexec\fR(2)).
248 .RE
250 .sp
251 .LP
252 Values for \fBl_type\fR used for record locking with \fBfcntl()\fR (the
253 following values are unique):
254 .sp
255 .ne 2
256 .na
257 \fB\fBF_RDLCK\fR\fR
258 .ad
259 .RS 11n
260 Shared or read lock.
261 .RE
263 .sp
264 .ne 2
265 .na
266 \fB\fBF_UNLCK\fR\fR
267 .ad
268 .RS 11n
269 Unlock.
270 .RE
272 .sp
273 .ne 2
274 .na
275 \fB\fBF_WRLCK\fR\fR
276 .ad
277 .RS 11n
278 Exclusive or write lock.
279 .RE
281 .sp
282 .LP
283 Values for \fBf_access\fR used for share reservations with \fBfcntl()\fR (the
284 following values are unique):
285 .sp
286 .ne 2
287 .na
288 \fB\fBF_RDACC\fR\fR
289 .ad
290 .RS 11n
291 Read-only share reservation.
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fBF_WRACC\fR\fR
298 .ad
299 .RS 11n
300 Write-only share reservation.
301 .RE
303 .sp
304 .ne 2
305 .na
306 \fB\fBF_RWACC\fR\fR
307 .ad
308 .RS 11n
309 Read and write share reservation.
310 .RE
312 .sp
313 .LP
314 Values for \fBf_deny\fR used for share reservations with \fBfcntl()\fR (the
315 following values are unique):
316 .sp
317 .ne 2
318 .na
319 \fB\fBF_COMPAT\fR\fR
320 .ad
321 .RS 12n
322 Compatibility mode share reservation.
323 .RE
325 .sp
326 .ne 2
327 .na
328 \fB\fBF_RDDNY\fR\fR
329 .ad
330 .RS 12n
331 Deny other read access share reservations.
332 .RE
334 .sp
335 .ne 2
336 .na
337 \fB\fBF_WRDNY\fR\fR
338 .ad
339 .RS 12n
340 Deny other write access share reservations.
341 .RE
343 .sp
344 .ne 2
345 .na
346 \fB\fBF_RWDNY\fR\fR
347 .ad
348 .RS 12n
349 Deny other read or write access share reservations.
350 .RE
352 .sp
353 .ne 2
354 .na
355 \fB\fBF_NODNY\fR\fR
356 .ad
357 .RS 12n
358 Do not deny other read or write access share reservations.
359 .RE
361 .sp
362 .LP
363 File creation and assignment flags are used in the \fIoflag\fR argument by
364 \fBopen()\fR and \fBopenat()\fR. All of these values are bitwise distinct:
365 .sp
366 .ne 2
367 .na
368 \fB\fBO_CREAT\fR\fR
369 .ad
370 .RS 12n
371 Create file if it does not exist.
372 .RE
374 .sp
375 .ne 2
376 .na
377 \fB\fBO_EXCL\fR\fR
378 .ad
379 .RS 12n
380 Exclusive use flag.
381 .RE
383 .sp
384 .ne 2
385 .na
386 \fB\fBO_NOCTTY\fR\fR
387 .ad
388 .RS 12n
389 Do not assign controlling tty.
390 .RE
392 .sp
393 .ne 2
394 .na
395 \fB\fBO_TRUNC\fR\fR
396 .ad
397 .RS 12n
398 Truncate flag.
399 .RE
401 .sp
402 .ne 2
403 .na
404 \fB\fBO_XATTR\fR\fR
405 .ad
406 .RS 12n
407 When opening a file, this flag affects the way in which relative paths are
408 resolved by \fBopen()\fR and \fBopenat()\fR. With this flag set, the
409 \fIpath\fR argument is resolved as an extended attribute reference on either
410 the current working directory (if open) or of the file referenced by the file
411 descriptor argument of \fBopenat()\fR.
412 .RE
414 .sp
415 .LP
416 File status flags used for \fBfcntl()\fR, \fBopen()\fR, and \fBopen()\fR:
417 .sp
418 .ne 2
419 .na
420 \fB\fBO_APPEND\fR\fR
421 .ad
422 .RS 14n
423 Set append mode.
424 .RE
426 .sp
427 .ne 2
428 .na
429 \fB\fBO_NDELAY\fR\fR
430 .ad
431 .RS 14n
432 Non-blocking mode.
433 .RE
435 .sp
436 .ne 2
437 .na
438 \fB\fBO_NONBLOCK\fR\fR
439 .ad
440 .RS 14n
441 Non-blocking mode (POSIX; see \fBstandards\fR(5)).
442 .RE
444 .sp
445 .ne 2
446 .na
447 \fB\fBO_DSYNC\fR\fR
448 .ad
449 .RS 14n
450 Write I/O operations on the file descriptor complete as defined by synchronized
451 I/O data integrity completion.
452 .RE
454 .sp
455 .ne 2
456 .na
457 \fB\fBO_RSYNC\fR\fR
458 .ad
459 .RS 14n
460 Read I/O operations on the file descriptor complete at the same level of
461 integrity as specified by the \fBO_DSYNC\fR and \fBO_SYNC\fR flags. If both
462 \fBO_DSYNC\fR and \fBO_RSYNC\fR are set in \fIoflag\fR, all I/O operations on
463 the file descriptor complete as defined by synchronized I/O data integrity
464 completion. If both \fBO_SYNC\fR and \fBO_RSYNC\fR are set in \fIoflag\fR,
465 all I/O operations on the file descriptor complete as defined by synchronized
466 I/O file integrity completion.
467 .RE
469 .sp
470 .ne 2
471 .na
472 \fB\fBO_SYNC\fR\fR
473 .ad
474 .RS 14n
475 When opening a regular file, this flag affects subsequent writes. If set, each
476 \fBwrite\fR(2) will wait for both the file data and file status to be
477 physically updated. Write I/O operations on the file descriptor complete as
478 defined by synchronized I/O file integrity completion.
479 .RE
481 .sp
482 .LP
483 Mask for use with file access modes:
484 .sp
485 .ne 2
486 .na
487 \fB\fBO_ACCMODE\fR\fR
488 .ad
489 .RS 13n
490 Mask for file access modes.
491 .RE
493 .sp
494 .LP
495 File access modes used for \fBfcntl()\fR, \fBopen()\fR, and \fBopenat()\fR:
496 .sp
497 .ne 2
498 .na
499 \fB\fBO_RDONLY\fR\fR
500 .ad
501 .RS 12n
502 Open for reading only.
503 .RE
505 .sp
506 .ne 2
507 .na
508 \fB\fBO_RDWR\fR\fR
509 .ad
510 .RS 12n
511 Open for reading and writing.
512 .RE
514 .sp
515 .ne 2
516 .na
517 \fB\fBO_WRONLY\fR\fR
518 .ad
519 .RS 12n
520 Open for writing only.
521 .RE
523 .sp
524 .LP
525 The following constants are used by system calls capable of resolving paths
526 relative to a provided open file descriptor:
527 .sp
528 .ne 2
529 .na
530 \fB\fBAT_FDCWD\fR\fR
531 .ad
532 .RS 23n
533 Special value to pass in place of a file descriptor to inform the called
534 routine that relative path arguments should be resolved from the current
535 working directory.
536 .RE
538 .sp
539 .ne 2
540 .na
541 \fB\fBAT_SYMLINK_NOFOLLOW\fR\fR
542 .ad
543 .RS 23n
544 Flag passed to \fBfstatat\fR(2) and \fBfchownat\fR(2) to change the behavior of
545 these functions when they are given a file as an argument that is a symbolic
546 link. In this case the functions operate on the symbolic link file rather than
547 the file the link references.
548 .RE
550 .sp
551 .ne 2
552 .na
553 \fB\fBAT_REMOVEDIR\fR\fR
554 .ad
555 .RS 23n
556 Flag passed to \fBunlinkat\fR(2) to tell it to assume that its path argument
557 refers to a directory and to attempt to remove this directory.
558 .RE
560 .sp
561 .LP
562 The \fBflock\fR structure describes a file lock. It includes the following
563 members:
564 .sp
565 .in +2
566 .nf
567 short l_type; /* Type of lock */
568 short l_whence; /* Flag for starting offset */
569 off_t l_start; /* Relative offset in bytes */
570 off_t l_len; /* Size; if 0 then until EOF */
571 long l_sysid; /* Returned with F_GETLK */
572 pid_t l_pid; /* Returned with F_GETLK */
573 .fi
574 .in -2
576 .sp
577 .LP
578 The structure \fBfshare\fR describes a file share reservation. It includes the
579 following members:
580 .sp
581 .in +2
582 .nf
583 short f_access; /* Type of reservation */
584 short f_deny; /* Type of reservations to deny */
585 long f_id; /* Process unique identifier */
586 .fi
587 .in -2
589 .SH ATTRIBUTES
590 .LP
591 See \fBattributes\fR(5) for descriptions of the following attributes:
592 .sp
594 .sp
595 .TS
596 box;
597 c | c
598 l | l .
599 ATTRIBUTE TYPE ATTRIBUTE VALUE
600 _
601 Interface Stability Committed
602 _
603 Standard See \fBstandards\fR(5).
604 .TE
606 .SH SEE ALSO
607 .LP
608 \fBcreat\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBopen\fR(2),
609 \fBfdatasync\fR(3C), \fBfsync\fR(3C), \fBfsattr\fR(5), \fBattributes\fR(5),
610 \fBstandards\fR(5)
611 .SH NOTES
612 .LP
613 Data is successfully transferred for a write operation to a regular file when
614 the system ensures that all data written is readable on any subsequent open of
615 the file (even one that follows a system or power failure) in the absence of a
616 failure of the physical storage medium.
617 .sp
618 .LP
619 Data is successfully transferred for a read operation when an image of the data
620 on the physical storage medium is available to the requesting process.
621 .sp
622 .LP
623 Synchronized I/O data integrity completion (see \fBfdatasync\fR(3C)):
624 .RS +4
625 .TP
626 .ie t \(bu
627 .el o
628 For reads, the operation has been completed or diagnosed if unsuccessful. The
629 read is complete only when an image of the data has been successfully
630 transferred to the requesting process. If there were any pending write requests
631 affecting the data to be read at the time that the synchronized read operation
632 was requested, these write requests will be successfully transferred prior to
633 reading the data.
634 .RE
635 .RS +4
636 .TP
637 .ie t \(bu
638 .el o
639 For writes, the operation has been completed or diagnosed if unsuccessful. The
640 write is complete only when the data specified in the write request is
641 successfully transferred, and all file system information required to retrieve
642 the data is successfully transferred.
643 .RE
644 .sp
645 .LP
646 File attributes that are not necessary for data retrieval (access time,
647 modification time, status change time) need not be successfully transferred
648 prior to returning to the calling process.
649 .sp
650 .LP
651 Synchronized I/O file integrity completion (see \fBfsync\fR(3C)):
652 .RS +4
653 .TP
654 .ie t \(bu
655 .el o
656 Identical to a synchronized I/O data integrity completion with the addition
657 that all file attributes relative to the I/O operation (including access time,
658 modification time, status change time) will be successfully transferred prior
659 to returning to the calling process.
660 .RE