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