]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/fcntl.2
xnu-1228.9.59.tar.gz
[apple/xnu.git] / bsd / man / man2 / fcntl.2
CommitLineData
9bccf70c
A
1.\" $NetBSD: fcntl.2,v 1.6 1995/02/27 12:32:29 cgd Exp $
2.\"
3.\" Copyright (c) 1983, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
16.\" This product includes software developed by the University of
17.\" California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94
35.\"
36.Dd January 12, 1994
37.Dt FCNTL 2
38.Os BSD 4.2
39.Sh NAME
40.Nm fcntl
41.Nd file control
42.Sh SYNOPSIS
43.Fd #include <fcntl.h>
44.Ft int
2d21ac55
A
45.Fo fcntl
46.Fa "int fildes"
47.Fa "int cmd"
48.Fa "..."
49.Fc
9bccf70c
A
50.Sh DESCRIPTION
51.Fn Fcntl
52provides for control over descriptors.
53The argument
2d21ac55 54.Fa fildes
9bccf70c
A
55is a descriptor to be operated on by
56.Fa cmd
57as follows:
58.Bl -tag -width F_WRITEBOOTSTRAPX
59.It Dv F_DUPFD
60Return a new descriptor as follows:
61.Pp
62.Bl -bullet -compact -offset 4n
63.It
64Lowest numbered available descriptor greater than or equal to
65.Fa arg .
66.It
67Same object references as the original descriptor.
68.It
69New descriptor shares the same file offset if the object
70was a file.
71.It
72Same access mode (read, write or read/write).
73.It
74Same file status flags (i.e., both file descriptors
75share the same file status flags).
76.It
77The close-on-exec flag associated with the new file descriptor
78is set to remain open across
79.Xr execv 2
80system calls.
81.El
82.It Dv F_GETFD
83Get the close-on-exec flag associated with the file descriptor
2d21ac55 84.Fa fildes .
9bccf70c
A
85If the low-order bit of the returned value is 0,
86the file will remain open across
87.Fn exec ,
88otherwise the file will be closed upon execution of
89.Fn exec
90.Fa ( arg
91is ignored).
92.It Dv F_SETFD
93Set the close-on-exec flag associated with
2d21ac55 94.Fa fildes
9bccf70c
A
95to the low order bit of
96.Fa arg
97(0 or 1 as above).
98.It Dv F_GETFL
99Get descriptor status flags, as described below
100.Fa ( arg
101is ignored).
102.It Dv F_SETFL
103Set descriptor status flags to
104.Fa arg .
105.It Dv F_GETOWN
106Get the process ID or process group
107currently receiving
108.Dv SIGIO
109and
110.Dv SIGURG
111signals; process groups are returned
112as negative values
113.Fa ( arg
114is ignored).
115.It Dv F_SETOWN
116Set the process or process group
117to receive
118.Dv SIGIO
119and
120.Dv SIGURG
121signals;
122process groups are specified by supplying
123.Fa arg
124as negative, otherwise
125.Fa arg
126is interpreted as a process ID.
2d21ac55
A
127.It Dv F_GETPATH
128Get the path of the file descriptor
129.Fa Fildes .
130The argument must be a buffer of size
131.Sy MAXPATHLEN
132or greater.
9bccf70c
A
133.It Dv F_PREALLOCATE
134Preallocate file storage space.
135.It Dv F_SETSIZE
136Truncate a file without zeroing space.
137The calling process must have root privileges.
138.It Dv F_RDADVISE
139Issue an advisory read async with no copy to user.
140.It Dv F_RDAHEAD
141Turn read ahead off/on.
142A zero value in
143.Fa arg
144disables read ahead.
145A non-zero value in
146.Fa arg
147turns read ahead on.
148.It Dv F_READBOOTSTRAP
149Read bootstrap from disk.
150.It Dv F_WRITEBOOTSTRAP
151Write bootstrap on disk.
152The calling process must have root privileges.
153.It Dv F_NOCACHE
154Turns data caching off/on. A non-zero value in
155.Fa arg
156turns data caching off.
157A value of zero in
158.Fa arg
159turns data caching on.
160.It Dv F_LOG2PHYS
161Get disk device information.
162Currently this only includes the
163disk device address that corresponds
164to the current file offset.
91447636
A
165.It Dv F_FULLFSYNC
166Does the same thing as
167.Xr fsync 2
168then asks the drive to
169flush all buffered data to
170the permanent storage device
171.Fa ( arg
172is ignored).
2d21ac55
A
173This is currently implemented on HFS, MS-DOS (FAT),
174and Universal Disk Format (UDF) file systems.
175The operation may take quite a while to complete.
176Certain FireWire drives have also been known
177to ignore the request to flush their buffered data.
9bccf70c
A
178.El
179.Pp
180The flags for the
181.Dv F_GETFL
182and
183.Dv F_SETFL
184commands are as follows:
185.Bl -tag -width O_NONBLOCKX -offset indent
186.It Dv O_NONBLOCK
187Non-blocking I/O; if no data is available to a
188.Xr read
189call, or if a
190.Xr write
191operation would block,
192the read or write call returns -1 with the error
193.Er EAGAIN .
194.It Dv O_APPEND
195Force each write to append at the end of file;
196corresponds to the
197.Dv O_APPEND
198flag of
199.Xr open 2 .
200.It Dv O_ASYNC
201Enable the
202.Dv SIGIO
203signal to be sent to the process group
204when I/O is possible, e.g.,
205upon availability of data to be read.
206.El
207.Pp
208Several commands are available for doing advisory file locking;
209they all operate on the following structure:
210.ne 7v
211.Bd -literal
212 struct flock {
213 off_t l_start; /* starting offset */
214 off_t l_len; /* len = 0 means until end of file */
215 pid_t l_pid; /* lock owner */
216 short l_type; /* lock type: read/write, etc. */
217 short l_whence; /* type of l_start */
218 };
219.Ed
220.Pp
221The commands available for advisory record locking are as follows:
222.Bl -tag -width F_SETLKWX
223.It Dv F_GETLK
224Get the first lock that blocks the lock description pointed to by the
225third argument,
226.Fa arg ,
227taken as a pointer to a
228.Fa "struct flock"
229(see above).
230The information retrieved overwrites the information passed to
231.Nm fcntl
232in the
233.Fa flock
234structure.
235If no lock is found that would prevent this lock from being created,
236the structure is left unchanged by this function call except for the
237lock type which is set to
238.Dv F_UNLCK .
239.It Dv F_SETLK
240Set or clear a file segment lock according to the lock description
241pointed to by the third argument,
242.Fa arg ,
243taken as a pointer to a
244.Fa "struct flock"
245(see above).
246.Dv F_SETLK
247is used to establish shared (or read) locks
248.Dv (F_RDLCK)
249or exclusive (or write) locks,
250.Dv (F_WRLCK) ,
251as well as remove either type of lock
252.Dv (F_UNLCK) .
253If a shared or exclusive lock cannot be set,
254.Nm fcntl
255returns immediately with
256.Er EACCES .
257.It Dv F_SETLKW
258This command is the same as
259.Dv F_SETLK
260except that if a shared or exclusive lock is blocked by other locks,
261the process waits until the request can be satisfied.
262If a signal that is to be caught is received while
263.Nm fcntl
264is waiting for a region, the
265.Nm fcntl
266will be interrupted if the signal handler has not specified the
267.Dv SA_RESTART
268(see
269.Xr sigaction 2 ) .
270.El
271.Pp
272When a shared lock has been set on a segment of a file,
273other processes can set shared locks on that segment
274or a portion of it.
275A shared lock prevents any other process from setting an exclusive
276lock on any portion of the protected area.
277A request for a shared lock fails if the file descriptor was not
278opened with read access.
279.Pp
280An exclusive lock prevents any other process from setting a shared lock or
281an exclusive lock on any portion of the protected area.
282A request for an exclusive lock fails if the file was not
283opened with write access.
284.Pp
285The value of
286.Fa l_whence
287is
288.Dv SEEK_SET ,
289.Dv SEEK_CUR ,
290or
291.Dv SEEK_END
292to indicate that the relative offset,
293.Fa l_start
294bytes, will be measured from the start of the file,
295current position, or end of the file, respectively.
296The value of
297.Fa l_len
298is the number of consecutive bytes to be locked.
299If
300.Fa l_len
301is negative, the result is undefined.
302The
303.Fa l_pid
304field is only used with
305.Dv F_GETLK
306to return the process ID of the process holding a blocking lock.
307After a successful
308.Dv F_GETLK
309request, the value of
310.Fa l_whence
311is
312.Dv SEEK_SET .
313.Pp
314Locks may start and extend beyond the current end of a file,
315but may not start or extend before the beginning of the file.
316A lock is set to extend to the largest possible value of the
317file offset for that file if
318.Fa l_len
319is set to zero. If
320.Fa l_whence
321and
322.Fa l_start
323point to the beginning of the file, and
324.Fa l_len
325is zero, the entire file is locked.
326If an application wishes only to do entire file locking, the
327.Xr flock 2
328system call is much more efficient.
329.Pp
330There is at most one type of lock set for each byte in the file.
331Before a successful return from an
332.Dv F_SETLK
333or an
334.Dv F_SETLKW
335request when the calling process has previously existing locks
336on bytes in the region specified by the request,
337the previous lock type for each byte in the specified
338region is replaced by the new lock type.
339As specified above under the descriptions
340of shared locks and exclusive locks, an
341.Dv F_SETLK
342or an
343.Dv F_SETLKW
344request fails or blocks respectively when another process has existing
345locks on bytes in the specified region and the type of any of those
346locks conflicts with the type specified in the request.
347.Pp
348This interface follows the completely stupid semantics of System V and
349.St -p1003.1-88
350that require that all locks associated with a file for a given process are
351removed when \fIany\fP file descriptor for that file is closed by that process.
352This semantic means that applications must be aware of any files that
353a subroutine library may access.
354For example if an application for updating the password file locks the
355password file database while making the update, and then calls
356.Xr getpwname 3
357to retrieve a record,
358the lock will be lost because
359.Xr getpwname 3
360opens, reads, and closes the password database.
361The database close will release all locks that the process has
362associated with the database, even if the library routine never
363requested a lock on the database.
364Another minor semantic problem with this interface is that
365locks are not inherited by a child process created using the
366.Xr fork 2
367function.
368The
369.Xr flock 2
370interface has much more rational last close semantics and
371allows locks to be inherited by child processes.
372.Xr Flock 2
373is recommended for applications that want to ensure the integrity
374of their locks when using library routines or wish to pass locks
375to their children.
376Note that
377.Xr flock 2
378and
379.Xr fcntl 2
380locks may be safely used concurrently.
381.Pp
382All locks associated with a file for a given process are
383removed when the process terminates.
384.Pp
385A potential for deadlock occurs if a process controlling a locked region
386is put to sleep by attempting to lock the locked region of another process.
387This implementation detects that sleeping until a locked region is unlocked
388would cause a deadlock and fails with an
389.Er EDEADLK
390error.
391.Pp
392The
393.Dv F_PREALLOCATE
394command operates on the following structure:
395.ne 7v
396.Bd -literal
397 typedef struct fstore {
398 u_int32_t fst_flags; /* IN: flags word */
399 int fst_posmode; /* IN: indicates offset field */
400 off_t fst_offset; /* IN: start of the region */
401 off_t fst_length; /* IN: size of the region */
402 off_t fst_bytesalloc; /* OUT: number of bytes allocated */
403 } fstore_t;
404.Ed
405.Pp
406The flags (fst_flags) for the
407.Dv F_PREALLOCATE
408command are as follows:
409.Bl -tag -width F_ALLOCATECONTIGX -offset indent
410.It Dv F_ALLOCATECONTIG
411Allocate contiguous space.
412.It Dv F_ALLOCATEALL
413Allocate all requested space or no space at all.
414.El
415.Pp
416The position modes (fst_posmode) for the
417.Dv F_PREALLOCATE
418command indicate how to use the offset field.
419The modes are as follows:
420.Bl -tag -width F_PEOFPOSMODEX -offset indent
421.It Dv F_PEOFPOSMODE
422Allocate from the physical end of file.
423.It Dv F_VOLPOSMODE
424Allocate from the volume offset.
425.El
426.Pp
427The
428.Dv F_RDADVISE
429command operates on the following structure
430which holds information passed from the
431user to the system:
432.ne 7v
433.Bd -literal
434 struct radvisory {
435 off_t ra_offset; /* offset into the file */
436 int ra_count; /* size of the read */
437 };
438.Ed
439.Pp
440The
441.Dv F_READBOOTSTRAP and F_WRITEBOOTSTRAP
442commands operate on the following structure.
443.ne 7v
444.Bd -literal
445 typedef struct fbootstraptransfer {
446 off_t fbt_offset; /* IN: offset to start read/write */
447 size_t fbt_length; /* IN: number of bytes to transfer */
448 void *fbt_buffer; /* IN: buffer to be read/written */
449 } fbootstraptransfer_t;
450.Ed
451.Pp
452The
453.Dv F_LOG2PHYS
454command operates on the following structure.
455.ne 7v
456.Bd -literal
457 struct log2phys {
458 u_int32_t l2p_flags; /* unused so far */
459 off_t l2p_contigbytes; /* unused so far */
460 off_t l2p_devoffset; /* bytes into device */
461 };
462.Ed
463.Sh RETURN VALUES
464Upon successful completion, the value returned depends on
465.Fa cmd
466as follows:
467.Bl -tag -width F_GETOWNX -offset indent
468.It Dv F_DUPFD
469A new file descriptor.
470.It Dv F_GETFD
471Value of flag (only the low-order bit is defined).
472.It Dv F_GETFL
473Value of flags.
474.It Dv F_GETOWN
475Value of file descriptor owner.
476.It other
477Value other than -1.
478.El
479.Pp
480Otherwise, a value of -1 is returned and
481.Va errno
482is set to indicate the error.
483.Sh ERRORS
2d21ac55
A
484The
485.Fn fcntl
486system call will fail if:
9bccf70c 487.Bl -tag -width Er
2d21ac55 488.\" ==========
9bccf70c
A
489.It Bq Er EACCES
490The argument
491.Fa cmd
492is
493.Dv F_SETLK ,
494the type of lock
495.Fa (l_type)
496is a shared lock
497.Dv (F_RDLCK)
498or exclusive lock
499.Dv (F_WRLCK) ,
500and the segment of a file to be locked is already
501exclusive-locked by another process;
502or the type is an exclusive lock and some portion of the
503segment of a file to be locked is already shared-locked or
504exclusive-locked by another process.
505.Pp
506The argument
507.Fa cmd
508is either
509.Dv F_SETSIZE
510or
511.Dv F_WRITEBOOTSTRAP
512and the calling process does not have root privileges.
2d21ac55 513.\" ==========
9bccf70c
A
514.It Bq Er EBADF
515.Fa Fildes
516is not a valid open file descriptor.
517.Pp
518The argument
519.Fa cmd
520is
521.Dv F_SETLK
522or
523.Dv F_SETLKW ,
524the type of lock
525.Fa (l_type)
526is a shared lock
527.Dv (F_RDLCK) ,
528and
529.Fa fildes
530is not a valid file descriptor open for reading.
531.Pp
532The argument
533.Fa cmd
534is
535.Dv F_SETLK
536or
537.Dv F_SETLKW ,
538the type of lock
539.Fa (l_type)
540is an exclusive lock
541.Dv (F_WRLCK) ,
542and
543.Fa fildes
544is not a valid file descriptor open for writing.
545.Pp
546The argument
547.Fa cmd
548is
549.Dv F_PREALLOCATE
550and the calling process does not have
551file write permission.
552.Pp
553The argument
554.Fa cmd
555is
556.Dv F_LOG2PHYS
557and
558.Fa fildes
559is not a valid file descriptor open for reading.
2d21ac55 560.\" ==========
9bccf70c
A
561.It Bq Er EDEADLK
562The argument
563.Fa cmd
564is
565.Dv F_SETLKW ,
566and a deadlock condition was detected.
2d21ac55 567.\" ==========
9bccf70c
A
568.It Bq Er EINTR
569The argument
570.Fa cmd
571is
572.Dv F_SETLKW ,
573and the function was interrupted by a signal.
2d21ac55 574.\" ==========
9bccf70c
A
575.It Bq Er EINVAL
576.Fa Cmd
577is
578.Dv F_DUPFD
579and
580.Fa arg
581is negative or greater than the maximum allowable number
582(see
583.Xr getdtablesize 2 ) .
584.Pp
585The argument
586.Fa cmd
587is
588.Dv F_GETLK ,
589.Dv F_SETLK ,
590or
591.Dv F_SETLKW
592and the data to which
593.Fa arg
594points is not valid, or
595.Fa fildes
596refers to a file that does not support locking.
597.Pp
598The argument
599.Fa cmd
600is
601.Dv F_PREALLOCATE
602and the
603.Fa fst_posmode
604is not a valid mode,
605or when
606.Dv F_PEOFPOSMODE
607is set and
608.Fa fst_offset
609is a non-zero value,
610or when
611.Dv F_VOLPOSMODE
612is set and
613.Fa fst_offset
614is a negative or zero value.
615.Pp
616The argument
617.Fa cmd
618is either
619.Dv F_READBOOTSTRAP
620or
621.Dv F_WRITEBOOTSTRAP
622and the operation was attempted on a non-HFS disk type.
2d21ac55
A
623.\" ==========
624.It Bq Er EMFILE
625.Fa Cmd
626is
627.Dv F_DUPFD
628and the maximum allowed number of file descriptors are currently
629open.
630.\" ==========
9bccf70c
A
631.It Bq Er EMFILE
632The argument
633.Fa cmd
634is
635.Dv F_DUPED
636and the maximum number of file descriptors permitted for the
637process are already in use,
638or no file descriptors greater than or equal to
639.Fa arg
640are available.
2d21ac55 641.\" ==========
9bccf70c
A
642.It Bq Er ENOLCK
643The argument
644.Fa cmd
645is
646.Dv F_SETLK
647or
648.Dv F_SETLKW ,
649and satisfying the lock or unlock request would result in the
650number of locked regions in the system exceeding a system-imposed limit.
2d21ac55
A
651.\" ==========
652.It Bq Er EOVERFLOW
653A return value would overflow its representation.
654For example,
655.Fa cmd
656is F_GETLK, F_SETLK, or F_SETLKW
657and the smallest (or, if l_len is non-zero, the largest) offset
658of a byte in the requested segment
659will not fit in an object of type off_t.
660.\" ==========
9bccf70c
A
661.It Bq Er ESRCH
662.Fa Cmd
663is
664.Dv F_SETOWN
665and
666the process ID given as argument is not in use.
667.El
668.Sh SEE ALSO
669.Xr close 2 ,
670.Xr execve 2 ,
671.Xr flock 2 ,
672.Xr getdtablesize 2 ,
673.Xr open 2 ,
674.Xr sigaction 3
675.Sh HISTORY
676The
677.Fn fcntl
678function call appeared in
679.Bx 4.2 .