xref: /openbsd/lib/libc/sys/fcntl.2 (revision f2dfb0a4) 
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
45.Fn fcntl "int fd" "int cmd" "int arg"
46.Sh DESCRIPTION
47.Fn Fcntl
48provides for control over descriptors.
49The argument
50.Fa fd
51is a descriptor to be operated on by
52.Fa cmd
53as follows:
54.Bl -tag -width F_GETOWNX
55.It Dv F_DUPFD
56Return a new descriptor as follows:
57.Pp
58.Bl -bullet -compact -offset 4n
59.It
60Lowest numbered available descriptor greater than or equal to
61.Fa arg .
62.It
63Same object references as the original descriptor.
64.It
65New descriptor shares the same file offset if the object
66was a file.
67.It
68Same access mode (read, write or read/write).
69.It
70Same file status flags (i.e., both file descriptors
71share the same file status flags).
72.It
73The close-on-exec flag associated with the new file descriptor
74is set to remain open across
75.Xr execv 2
76system calls.
77.El
78.It Dv F_GETFD
79Get the close-on-exec flag associated with the file descriptor
80.Fa fd .
81If the low-order bit of the returned value is 0,
82the file will remain open across
83.Fn exec ,
84otherwise the file will be closed upon execution of
85.Fn exec
86.Fa ( arg
87is ignored).
88.It Dv F_SETFD
89Set the close-on-exec flag associated with
90.Fa fd
91to the low order bit of
92.Fa arg
93(0 or 1 as above).
94.It Dv F_GETFL
95Get descriptor status flags, as described below
96.Fa ( arg
97is ignored).
98.It Dv F_SETFL
99Set descriptor status flags to
100.Fa arg .
101.It Dv F_GETOWN
102Get the process ID or process group
103currently receiving
104.Dv SIGIO
105and
106.Dv SIGURG
107signals; process groups are returned
108as negative values
109.Fa ( arg
110is ignored).
111.It Dv F_SETOWN
112Set the process or process group
113to receive
114.Dv SIGIO
115and
116.Dv SIGURG
117signals;
118process groups are specified by supplying
119.Fa arg
120as negative, otherwise
121.Fa arg
122is interpreted as a process ID.
123.El
124.Pp
125The flags for the
126.Dv F_GETFL
127and
128.Dv F_SETFL
129flags are as follows:
130.Bl -tag -width O_NONBLOCKX
131.It Dv O_NONBLOCK
132Non-blocking I/O; if no data is available to a
133.Xr read 2
134call, or if a
135.Xr write 2
136operation would block,
137the read or write call returns -1 with the error
138.Er EAGAIN .
139.It Dv O_APPEND
140Force each write to append at the end of file;
141corresponds to the
142.Dv O_APPEND
143flag of
144.Xr open 2 .
145.It Dv O_ASYNC
146Enable the
147.Dv SIGIO
148signal to be sent to the process group
149when I/O is possible, e.g.,
150upon availability of data to be read.
151.El
152.Pp
153Several commands are available for doing advisory file locking;
154they all operate on the following structure:
155.ne 7v
156.Bd -literal
157struct flock {
158	off_t	l_start;	/* starting offset */
159	off_t	l_len;		/* len = 0 means until end of file */
160	pid_t	l_pid;		/* lock owner */
161	short	l_type;		/* lock type: read/write, etc. */
162	short	l_whence;	/* type of l_start */
163};
164.Ed
165.Pp
166The commands available for advisory record locking are as follows:
167.Bl -tag -width F_SETLKWX
168.It Dv F_GETLK
169Get the first lock that blocks the lock description pointed to by the
170third argument,
171.Fa arg ,
172taken as a pointer to a
173.Fa "struct flock"
174(see above).
175The information retrieved overwrites the information passed to
176.Nm fcntl
177in the
178.Fa flock
179structure.
180If no lock is found that would prevent this lock from being created,
181the structure is left unchanged by this function call except for the
182lock type which is set to
183.Dv F_UNLCK .
184.It Dv F_SETLK
185Set or clear a file segment lock according to the lock description
186pointed to by the third argument,
187.Fa arg ,
188taken as a pointer to a
189.Fa "struct flock"
190(see above).
191.Dv F_SETLK
192is used to establish shared (or read) locks
193.Dv (F_RDLCK)
194or exclusive (or write) locks,
195.Dv (F_WRLCK) ,
196as well as remove either type of lock
197.Dv (F_UNLCK) .
198If a shared or exclusive lock cannot be set,
199.Nm fcntl
200returns immediately with
201.Er EAGAIN .
202.It Dv F_SETLKW
203This command is the same as
204.Dv F_SETLK
205except that if a shared or exclusive lock is blocked by other locks,
206the process waits until the request can be satisfied.
207If a signal that is to be caught is received while
208.Nm fcntl
209is waiting for a region, the
210.Nm fcntl
211will be interrupted if the signal handler has not specified the
212.Dv SA_RESTART
213(see
214.Xr sigaction 2 ) .
215.El
216.Pp
217When a shared lock has been set on a segment of a file,
218other processes can set shared locks on that segment
219or a portion of it.
220A shared lock prevents any other process from setting an exclusive
221lock on any portion of the protected area.
222A request for a shared lock fails if the file descriptor was not
223opened with read access.
224.Pp
225An exclusive lock prevents any other process from setting a shared lock or
226an exclusive lock on any portion of the protected area.
227A request for an exclusive lock fails if the file was not
228opened with write access.
229.Pp
230The value of
231.Fa l_whence
232is
233.Dv SEEK_SET ,
234.Dv SEEK_CUR ,
235or
236.Dv SEEK_END
237to indicate that the relative offset,
238.Fa l_start
239bytes, will be measured from the start of the file,
240current position, or end of the file, respectively.
241The value of
242.Fa l_len
243is the number of consecutive bytes to be locked.
244If
245.Fa l_len
246is negative, the result is undefined.
247The
248.Fa l_pid
249field is only used with
250.Dv F_GETLK
251to return the process ID of the process holding a blocking lock.
252After a successful
253.Dv F_GETLK
254request, the value of
255.Fa l_whence
256is
257.Dv SEEK_SET .
258.Pp
259Locks may start and extend beyond the current end of a file,
260but may not start or extend before the beginning of the file.
261A lock is set to extend to the largest possible value of the
262file offset for that file if
263.Fa l_len
264is set to zero. If
265.Fa l_whence
266and
267.Fa l_start
268point to the beginning of the file, and
269.Fa l_len
270is zero, the entire file is locked.
271If an application wishes only to do entire file locking, the
272.Xr flock 2
273system call is much more efficient.
274.Pp
275There is at most one type of lock set for each byte in the file.
276Before a successful return from an
277.Dv F_SETLK
278or an
279.Dv F_SETLKW
280request when the calling process has previously existing locks
281on bytes in the region specified by the request,
282the previous lock type for each byte in the specified
283region is replaced by the new lock type.
284As specified above under the descriptions
285of shared locks and exclusive locks, an
286.Dv F_SETLK
287or an
288.Dv F_SETLKW
289request fails or blocks respectively when another process has existing
290locks on bytes in the specified region and the type of any of those
291locks conflicts with the type specified in the request.
292.Pp
293This interface follows the completely stupid semantics of System V and
294.St -p1003.1-88
295that require that all locks associated with a file for a given process are
296removed when \fIany\fP file descriptor for that file is closed by that process.
297This semantic means that applications must be aware of any files that
298a subroutine library may access.
299For example if an application for updating the password file locks the
300password file database while making the update, and then calls
301.Xr getpwname 3
302to retrieve a record,
303the lock will be lost because
304.Xr getpwname 3
305opens, reads, and closes the password database.
306The database close will release all locks that the process has
307associated with the database, even if the library routine never
308requested a lock on the database.
309Another minor semantic problem with this interface is that
310locks are not inherited by a child process created using the
311.Xr fork 2
312function.
313The
314.Xr flock 2
315interface has much more rational last close semantics and
316allows locks to be inherited by child processes.
317.Xr Flock 2
318is recommended for applications that want to ensure the integrity
319of their locks when using library routines or wish to pass locks
320to their children.
321Note that
322.Xr flock 2
323and
324.Xr fcntl 2
325locks may be safely used concurrently.
326.Pp
327All locks associated with a file for a given process are
328removed when the process terminates.
329.Pp
330A potential for deadlock occurs if a process controlling a locked region
331is put to sleep by attempting to lock the locked region of another process.
332This implementation detects that sleeping until a locked region is unlocked
333would cause a deadlock and fails with an
334.Er EDEADLK
335error.
336.Sh RETURN VALUES
337Upon successful completion, the value returned depends on
338.Fa cmd
339as follows:
340.Bl -tag -width F_GETOWNX -offset indent
341.It Dv F_DUPFD
342A new file descriptor.
343.It Dv F_GETFD
344Value of flag (only the low-order bit is defined).
345.It Dv F_GETFL
346Value of flags.
347.It Dv F_GETOWN
348Value of file descriptor owner.
349.It other
350Value other than -1.
351.El
352.Pp
353Otherwise, a value of -1 is returned and
354.Va errno
355is set to indicate the error.
356.Sh ERRORS
357.Fn Fcntl
358will fail if:
359.Bl -tag -width Er
360.It Bq Er EAGAIN
361The argument
362.Fa cmd
363is
364.Dv F_SETLK ,
365the type of lock
366.Fa (l_type)
367is a shared lock
368.Dv (F_RDLCK)
369or exclusive lock
370.Dv (F_WRLCK) ,
371and the segment of a file to be locked is already
372exclusive-locked by another process;
373or the type is an exclusive lock and some portion of the
374segment of a file to be locked is already shared-locked or
375exclusive-locked by another process.
376.It Bq Er EBADF
377.Fa Fildes
378is not a valid open file descriptor.
379.Pp
380The argument
381.Fa cmd
382is
383.Dv F_SETLK
384or
385.Dv F_SETLKW ,
386the type of lock
387.Fa (l_type)
388is a shared lock
389.Dv (F_RDLCK) ,
390and
391.Fa fildes
392is not a valid file descriptor open for reading.
393.Pp
394The argument
395.Fa cmd
396is
397.Dv F_SETLK
398or
399.Dv F_SETLKW ,
400the type of lock
401.Fa (l_type)
402is an exclusive lock
403.Dv (F_WRLCK) ,
404and
405.Fa fildes
406is not a valid file descriptor open for writing.
407.It Bq Er EMFILE
408.Fa Cmd
409is
410.Dv F_DUPFD
411and the maximum allowed number of file descriptors are currently
412open.
413.It Bq Er EDEADLK
414The argument
415.Fa cmd
416is
417.Dv F_SETLKW ,
418and a deadlock condition was detected.
419.It Bq Er EINTR
420The argument
421.Fa cmd
422is
423.Dv F_SETLKW ,
424and the function was interrupted by a signal.
425.It Bq Er EINVAL
426.Fa Cmd
427is
428.Dv F_DUPFD
429and
430.Fa arg
431is negative or greater than the maximum allowable number
432(see
433.Xr getdtablesize 3 ) .
434.Pp
435The argument
436.Fa cmd
437is
438.Dv F_GETLK ,
439.Dv F_SETLK ,
440or
441.Dv F_SETLKW
442and the data to which
443.Fa arg
444points is not valid, or
445.Fa fildes
446refers to a file that does not support locking.
447.It Bq Er EMFILE
448The argument
449.Fa cmd
450is
451.Dv F_DUPFD
452and the maximum number of file descriptors permitted for the
453process are already in use,
454or no file descriptors greater than or equal to
455.Fa arg
456are available.
457.It Bq Er ENOLCK
458The argument
459.Fa cmd
460is
461.Dv F_SETLK
462or
463.Dv F_SETLKW ,
464and satisfying the lock or unlock request would result in the
465number of locked regions in the system exceeding a system-imposed limit.
466.It Bq Er ESRCH
467.Fa Cmd
468is
469.Dv F_SETOWN
470and
471the process ID given as argument is not in use.
472.El
473.Sh SEE ALSO
474.Xr close 2 ,
475.Xr execve 2 ,
476.Xr flock 2 ,
477.Xr getdtablesize 3 ,
478.Xr open 2 ,
479.Xr sigaction 3
480.Sh HISTORY
481The
482.Fn fcntl
483function call appeared in
484.Bx 4.2 .
485