xref: /netbsd-src/lib/libc/sys/fcntl.2 (revision 76dfffe33547c37f8bdd446e3e4ab0f3c16cea4b) 
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
134call, or if a
135.Xr write
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
165The commands available for advisory record locking are as follows:
166.Bl -tag -width F_SETLKWX
167.It Dv F_GETLK
168Get the first lock that blocks the lock description pointed to by the
169third argument,
170.Fa arg ,
171taken as a pointer to a
172.Fa "struct flock"
173(see above).
174The information retrieved overwrites the information passed to
175.Nm fcntl
176in the
177.Fa flock
178structure.
179If no lock is found that would prevent this lock from being created,
180the structure is left unchanged by this function call except for the
181lock type which is set to
182.Dv F_UNLCK .
183.It Dv F_SETLK
184Set or clear a file segment lock according to the lock description
185pointed to by the third argument,
186.Fa arg ,
187taken as a pointer to a
188.Fa "struct flock"
189(see above).
190.Dv F_SETLK
191is used to establish shared (or read) locks
192.Dv (F_RDLCK)
193or exclusive (or write) locks,
194.Dv (F_WRLCK) ,
195as well as remove either type of lock
196.Dv (F_UNLCK) .
197If a shared or exclusive lock cannot be set,
198.Nm fcntl
199returns immediately with
200.Er EACCES .
201.It Dv F_SETLKW
202This command is the same as
203.Dv F_SETLK
204except that if a shared or exclusive lock is blocked by other locks,
205the process waits until the request can be satisfied.
206If a signal that is to be caught is received while
207.Nm fcntl
208is waiting for a region, the
209.Nm fcntl
210will be interrupted if the signal handler has not specified the
211.Dv SA_RESTART
212(see
213.Xr sigaction 2 ) .
214.El
215.Pp
216When a shared lock has been set on a segment of a file,
217other processes can set shared locks on that segment
218or a portion of it.
219A shared lock prevents any other process from setting an exclusive
220lock on any portion of the protected area.
221A request for a shared lock fails if the file descriptor was not
222opened with read access.
223.Pp
224An exclusive lock prevents any other process from setting a shared lock or
225an exclusive lock on any portion of the protected area.
226A request for an exclusive lock fails if the file was not
227opened with write access.
228.Pp
229The value of
230.Fa l_whence
231is
232.Dv SEEK_SET ,
233.Dv SEEK_CUR ,
234or
235.Dv SEEK_END
236to indicate that the relative offset,
237.Fa l_start
238bytes, will be measured from the start of the file,
239current position, or end of the file, respectively.
240The value of
241.Fa l_len
242is the number of consecutive bytes to be locked.
243If
244.Fa l_len
245is negative, the result is undefined.
246The
247.Fa l_pid
248field is only used with
249.Dv F_GETLK
250to return the process ID of the process holding a blocking lock.
251After a successful
252.Dv F_GETLK
253request, the value of
254.Fa l_whence
255is
256.Dv SEEK_SET .
257.Pp
258Locks may start and extend beyond the current end of a file,
259but may not start or extend before the beginning of the file.
260A lock is set to extend to the largest possible value of the
261file offset for that file if
262.Fa l_len
263is set to zero. If
264.Fa l_whence
265and
266.Fa l_start
267point to the beginning of the file, and
268.Fa l_len
269is zero, the entire file is locked.
270If an application wishes only to do entire file locking, the
271.Xr flock 2
272system call is much more efficient.
273.Pp
274There is at most one type of lock set for each byte in the file.
275Before a successful return from an
276.Dv F_SETLK
277or an
278.Dv F_SETLKW
279request when the calling process has previously existing locks
280on bytes in the region specified by the request,
281the previous lock type for each byte in the specified
282region is replaced by the new lock type.
283As specified above under the descriptions
284of shared locks and exclusive locks, an
285.Dv F_SETLK
286or an
287.Dv F_SETLKW
288request fails or blocks respectively when another process has existing
289locks on bytes in the specified region and the type of any of those
290locks conflicts with the type specified in the request.
291.Pp
292This interface follows the completely stupid semantics of System V and
293.St -p1003.1-88
294that require that all locks associated with a file for a given process are
295removed when \fIany\fP file descriptor for that file is closed by that process.
296This semantic means that applications must be aware of any files that
297a subroutine library may access.
298For example if an application for updating the password file locks the
299password file database while making the update, and then calls
300.Xr getpwname 3
301to retrieve a record,
302the lock will be lost because
303.Xr getpwname 3
304opens, reads, and closes the password database.
305The database close will release all locks that the process has
306associated with the database, even if the library routine never
307requested a lock on the database.
308Another minor semantic problem with this interface is that
309locks are not inherited by a child process created using the
310.Xr fork 2
311function.
312The
313.Xr flock 2
314interface has much more rational last close semantics and
315allows locks to be inherited by child processes.
316.Xr Flock 2
317is recommended for applications that want to ensure the integrity
318of their locks when using library routines or wish to pass locks
319to their children.
320Note that
321.Xr flock 2
322and
323.Xr fcntl 2
324locks may be safely used concurrently.
325.Pp
326All locks associated with a file for a given process are
327removed when the process terminates.
328.Pp
329A potential for deadlock occurs if a process controlling a locked region
330is put to sleep by attempting to lock the locked region of another process.
331This implementation detects that sleeping until a locked region is unlocked
332would cause a deadlock and fails with an
333.Er EDEADLK
334error.
335.Sh RETURN VALUES
336Upon successful completion, the value returned depends on
337.Fa cmd
338as follows:
339.Bl -tag -width F_GETOWNX -offset indent
340.It Dv F_DUPFD
341A new file descriptor.
342.It Dv F_GETFD
343Value of flag (only the low-order bit is defined).
344.It Dv F_GETFL
345Value of flags.
346.It Dv F_GETOWN
347Value of file descriptor owner.
348.It other
349Value other than -1.
350.El
351.Pp
352Otherwise, a value of -1 is returned and
353.Va errno
354is set to indicate the error.
355.Sh ERRORS
356.Fn Fcntl
357will fail if:
358.Bl -tag -width Er
359.It Bq Er EACCES
360The argument
361.Fa arg
362is
363.Dv F_SETLK ,
364the type of lock
365.Fa (l_type)
366is a shared lock
367.Dv (F_RDLCK)
368or exclusive lock
369.Dv (F_WRLCK) ,
370and the segment of a file to be locked is already
371exclusive-locked by another process;
372or the type is an exclusive lock and some portion of the
373segment of a file to be locked is already shared-locked or
374exclusive-locked by another process.
375.It Bq Er EBADF
376.Fa Fildes
377is not a valid open file descriptor.
378.Pp
379The argument
380.Fa cmd
381is
382.Dv F_SETLK
383or
384.Dv F_SETLKW ,
385the type of lock
386.Fa (l_type)
387is a shared lock
388.Dv (F_RDLCK) ,
389and
390.Fa fildes
391is not a valid file descriptor open for reading.
392.Pp
393The argument
394.Fa cmd
395is
396.Dv F_SETLK
397or
398.Dv F_SETLKW ,
399the type of lock
400.Fa (l_type)
401is an exclusive lock
402.Dv (F_WRLCK) ,
403and
404.Fa fildes
405is not a valid file descriptor open for writing.
406.It Bq Er EMFILE
407.Fa Cmd
408is
409.Dv F_DUPFD
410and the maximum allowed number of file descriptors are currently
411open.
412.It Bq Er EDEADLK
413The argument
414.Fa cmd
415is
416.Dv F_SETLKW ,
417and a deadlock condition was detected.
418.It Bq Er EINTR
419The argument
420.Fa cmd
421is
422.Dv F_SETLKW ,
423and the function was interrupted by a signal.
424.It Bq Er EINVAL
425.Fa Cmd
426is
427.Dv F_DUPFD
428and
429.Fa arg
430is negative or greater than the maximum allowable number
431(see
432.Xr getdtablesize 2 ) .
433.Pp
434The argument
435.Fa cmd
436is
437.Dv F_GETLK ,
438.Dv F_SETLK ,
439or
440.Dv F_SETLKW
441and the data to which
442.Fa arg
443points is not valid, or
444.Fa fildes
445refers to a file that does not support locking.
446.It Bq Er EMFILE
447The argument
448.Fa cmd
449is
450.Dv F_DUPED
451and the maximum number of file descriptors permitted for the
452process are already in use,
453or no file descriptors greater than or equal to
454.Fa arg
455are available.
456.It Bq Er ENOLCK
457The argument
458.Fa cmd
459is
460.Dv F_SETLK
461or
462.Dv F_SETLKW ,
463and satisfying the lock or unlock request would result in the
464number of locked regions in the system exceeding a system-imposed limit.
465.It Bq Er ESRCH
466.Fa Cmd
467is
468.Dv F_SETOWN
469and
470the process ID given as argument is not in use.
471.El
472.Sh SEE ALSO
473.Xr close 2 ,
474.Xr execve 2 ,
475.Xr flock 2 ,
476.Xr getdtablesize 2 ,
477.Xr open 2 ,
478.Xr sigaction 3
479.Sh HISTORY
480The
481.Fn fcntl
482function call appeared in
483.Bx 4.2 .
484