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