bsd/man/man2/fcntl.2

   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 February 17, 2011
  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
  75 provides for control over descriptors.
  76 The argument
  77 .Fa fildes
  78 is a descriptor to be operated on by
  79 .Fa cmd
  80 as follows:
  81 .Bl -tag -width F_WRITEBOOTSTRAPX
  82 .It Dv F_DUPFD
  83 Return a new descriptor as follows:
  84 .Pp
  85 .Bl -bullet -compact -offset 4n
  86 .It
  87 Lowest numbered available descriptor greater than or equal to
  88 .Fa arg .
  89 .It
  90 Same object references as the original descriptor.
  91 .It
  92 New descriptor shares the same file offset if the object
  93 was a file.
  94 .It
  95 Same access mode (read, write or read/write).
  96 .It
  97 Same file status flags (i.e., both file descriptors
  98 share the same file status flags).
  99 .It
 100 The close-on-exec flag associated with the new file descriptor
 101 is cleared so that the descriptor remains open across an
 102 .Xr execv 2
 103 system call.
 104 .El
 105 .It Dv F_DUPFD_CLOEXEC
 106 Like
 107 .Dv F_DUPFD ,
 108 except that the close-on-exec flag associated with the new file descriptor
 109 is set.
 110 .It Dv F_GETFD
 111 Get the flags associated with the file descriptor
 112 .Fa fildes ,
 113 as described below
 114 .Fa ( arg
 115 is ignored).
 116 .It Dv F_SETFD
 117 Set the file descriptor flags to
 118 .Fa arg .
 119 .It Dv F_GETFL
 120 Get descriptor status flags, as described below
 121 .Fa ( arg
 122 is ignored).
 123 .It Dv F_SETFL
 124 Set descriptor status flags to
 125 .Fa arg .
 126 .It Dv F_GETOWN
 127 Get the process ID or process group
 128 currently receiving
 129 .Dv SIGIO
 130 and
 131 .Dv SIGURG
 132 signals; process groups are returned
 133 as negative values
 134 .Fa ( arg
 135 is ignored).
 136 .It Dv F_SETOWN
 137 Set the process or process group
 138 to receive
 139 .Dv SIGIO
 140 and
 141 .Dv SIGURG
 142 signals;
 143 process groups are specified by supplying
 144 .Fa arg
 145 as negative, otherwise
 146 .Fa arg
 147 is interpreted as a process ID.
 148 .It Dv F_GETPATH
 149 Get the path of the file descriptor
 150 .Fa Fildes .
 151 The argument must be a buffer of size
 152 .Sy MAXPATHLEN
 153 or greater.
 154 .It Dv F_PREALLOCATE
 155 Preallocate file storage space. Note: upon success,
 156 the space that is allocated can be the same size or
 157 larger than the space requested.
 158 .It Dv F_SETSIZE
 159 Truncate a file without zeroing space.
 160 The calling process must have root privileges.
 161 .It Dv F_RDADVISE
 162 Issue an advisory read async with no copy to user.
 163 .It Dv F_RDAHEAD
 164 Turn read ahead off/on.
 165 A zero value in
 166 .Fa arg
 167 disables read ahead.
 168 A non-zero value in
 169 .Fa arg
 170 turns read ahead on.
 171 .It Dv F_READBOOTSTRAP
 172 Read bootstrap from disk.
 173 .It Dv F_WRITEBOOTSTRAP
 174 Write bootstrap on disk.
 175 The calling process must have root privileges.
 176 .It Dv F_NOCACHE
 177 Turns data caching off/on. A non-zero value in
 178 .Fa arg
 179 turns data caching off.
 180 A value of zero in
 181 .Fa arg
 182 turns data caching on.
 183 .It Dv F_LOG2PHYS
 184 Get disk device information.
 185 Currently this only includes the
 186 disk device address that corresponds
 187 to the current file offset. Note that if the
 188 file offset is not backed by physical blocks
 189 we can return -1 as the offset. This is subject
 190 to change.
 191 .It Dv F_LOG2PHYS_EXT
 192 Variant of F_LOG2PHYS that uses the passed in
 193 file offset and length.
 194 .It Dv F_FULLFSYNC
 195 Does the same thing as
 196 .Xr fsync 2
 197 then asks the drive to
 198 flush all buffered data to
 199 the permanent storage device
 200 .Fa ( arg
 201 is ignored).
 202 This is currently implemented on HFS, MS-DOS (FAT),
 203 and Universal Disk Format (UDF) file systems.
 204 The operation may take quite a while to complete.
 205 Certain FireWire drives have also been known
 206 to ignore the request to flush their buffered data.
 207 .It Dv F_SETNOSIGPIPE
 208 Determines whether a
 209 .Dv SIGPIPE
 210 signal will be generated when a write fails on a pipe or socket for
 211 which there is no reader.  If
 212 .Fa arg
 213 is non-zero,
 214 .Dv SIGPIPE
 215 generation is disabled for descriptor
 216 .Fa fildes ,
 217 while an
 218 .Fa arg
 219 of zero enables it (the default).
 220 .It Dv F_GETNOSIGPIPE
 221 Returns whether a
 222 .Dv SIGPIPE
 223 signal will be generated when a write fails on a pipe or socket
 224 for which there is no reader.  The semantics of the return value
 225 match those of the
 226 .Fa arg
 227 of
 228 .Dv F_SETNOSIGPIPE .
 229 .El
 230 .Pp
 231 The flags for the
 232 .Dv F_GETFD
 233 and
 234 .Dv F_SETFD
 235 commands are as follows:
 236 .Bl -tag -width FD_CLOEXECX -offset indent
 237 .It Dv FD_CLOEXEC
 238 Close-on-exec; the given file descriptor will be automatically
 239 closed in the successor process image when one of the
 240 .Xr execv 2
 241 or
 242 .Xr posix_spawn 2
 243 family of system calls is invoked.
 244 .El
 245 .Pp
 246 The flags for the
 247 .Dv F_GETFL
 248 and
 249 .Dv F_SETFL
 250 commands are as follows:
 251 .Bl -tag -width O_NONBLOCKX -offset indent
 252 .It Dv O_NONBLOCK
 253 Non-blocking I/O; if no data is available to a
 254 .Xr read
 255 call, or if a
 256 .Xr write
 257 operation would block,
 258 the read or write call returns -1 with the error
 259 .Er EAGAIN .
 260 .It Dv O_APPEND
 261 Force each write to append at the end of file;
 262 corresponds to the
 263 .Dv O_APPEND
 264 flag of
 265 .Xr open 2 .
 266 .It Dv O_ASYNC
 267 Enable the
 268 .Dv SIGIO
 269 signal to be sent to the process group
 270 when I/O is possible, e.g.,
 271 upon availability of data to be read.
 272 .El
 273 .Pp
 274 Several commands are available for doing advisory file locking;
 275 they all operate on the following structure:
 276 .ne 7v
 277 .Bd -literal
 278         struct flock {
 279             off_t       l_start;    /* starting offset */
 280             off_t       l_len;      /* len = 0 means until end of file */
 281             pid_t       l_pid;      /* lock owner */
 282             short       l_type;     /* lock type: read/write, etc. */
 283             short       l_whence;   /* type of l_start */
 284         };
 285 .Ed
 286 .Pp
 287 The commands available for advisory record locking are as follows:
 288 .Bl -tag -width F_SETLKWX
 289 .It Dv F_GETLK
 290 Get the first lock that blocks the lock description pointed to by the
 291 third argument,
 292 .Fa arg ,
 293 taken as a pointer to a
 294 .Fa "struct flock"
 295 (see above).
 296 The information retrieved overwrites the information passed to
 297 .Nm fcntl
 298 in the
 299 .Fa flock
 300 structure.
 301 If no lock is found that would prevent this lock from being created,
 302 the structure is left unchanged by this function call except for the
 303 lock type which is set to
 304 .Dv F_UNLCK .
 305 .It Dv F_SETLK
 306 Set or clear a file segment lock according to the lock description
 307 pointed to by the third argument,
 308 .Fa arg ,
 309 taken as a pointer to a
 310 .Fa "struct flock"
 311 (see above).
 312 .Dv F_SETLK
 313 is used to establish shared (or read) locks
 314 .Dv (F_RDLCK)
 315 or exclusive (or write) locks,
 316 .Dv (F_WRLCK) ,
 317 as well as remove either type of lock
 318 .Dv (F_UNLCK) .
 319 If a shared or exclusive lock cannot be set,
 320 .Nm fcntl
 321 returns immediately with
 322 .Er EAGAIN .
 323 .It Dv F_SETLKW
 324 This command is the same as
 325 .Dv F_SETLK
 326 except that if a shared or exclusive lock is blocked by other locks,
 327 the process waits until the request can be satisfied.
 328 If a signal that is to be caught is received while
 329 .Nm fcntl
 330 is waiting for a region, the
 331 .Nm fcntl
 332 will be interrupted if the signal handler has not specified the
 333 .Dv SA_RESTART
 334 (see
 335 .Xr sigaction 2 ) .
 336 .El
 337 .Pp
 338 When a shared lock has been set on a segment of a file,
 339 other processes can set shared locks on that segment
 340 or a portion of it.
 341 A shared lock prevents any other process from setting an exclusive
 342 lock on any portion of the protected area.
 343 A request for a shared lock fails if the file descriptor was not
 344 opened with read access.
 345 .Pp
 346 An exclusive lock prevents any other process from setting a shared lock or
 347 an exclusive lock on any portion of the protected area.
 348 A request for an exclusive lock fails if the file was not
 349 opened with write access.
 350 .Pp
 351 The value of
 352 .Fa l_whence
 353 is
 354 .Dv SEEK_SET ,
 355 .Dv SEEK_CUR ,
 356 or
 357 .Dv SEEK_END
 358 to indicate that the relative offset,
 359 .Fa l_start
 360 bytes, will be measured from the start of the file,
 361 current position, or end of the file, respectively.
 362 The value of
 363 .Fa l_len
 364 is the number of consecutive bytes to be locked.
 365 If
 366 .Fa l_len
 367 is negative, the result is undefined.
 368 The
 369 .Fa l_pid
 370 field is only used with
 371 .Dv F_GETLK
 372 to return the process ID of the process holding a blocking lock.
 373 After a successful
 374 .Dv F_GETLK
 375 request, the value of
 376 .Fa l_whence
 377 is
 378 .Dv SEEK_SET .
 379 .Pp
 380 Locks may start and extend beyond the current end of a file,
 381 but may not start or extend before the beginning of the file.
 382 A lock is set to extend to the largest possible value of the
 383 file offset for that file if
 384 .Fa l_len
 385 is set to zero. If
 386 .Fa l_whence
 387 and
 388 .Fa l_start
 389 point to the beginning of the file, and
 390 .Fa l_len
 391 is zero, the entire file is locked.
 392 If an application wishes only to do entire file locking, the
 393 .Xr flock 2
 394 system call is much more efficient.
 395 .Pp
 396 There is at most one type of lock set for each byte in the file.
 397 Before a successful return from an
 398 .Dv F_SETLK
 399 or an
 400 .Dv F_SETLKW
 401 request when the calling process has previously existing locks
 402 on bytes in the region specified by the request,
 403 the previous lock type for each byte in the specified
 404 region is replaced by the new lock type.
 405 As specified above under the descriptions
 406 of shared locks and exclusive locks, an
 407 .Dv F_SETLK
 408 or an
 409 .Dv F_SETLKW
 410 request fails or blocks respectively when another process has existing
 411 locks on bytes in the specified region and the type of any of those
 412 locks conflicts with the type specified in the request.
 413 .Pp
 414 This interface follows the completely stupid semantics of System V and
 415 .St -p1003.1-88
 416 that require that all locks associated with a file for a given process are
 417 removed when \fIany\fP file descriptor for that file is closed by that process.
 418 This semantic means that applications must be aware of any files that
 419 a subroutine library may access.
 420 For example if an application for updating the password file locks the
 421 password file database while making the update, and then calls
 422 .Xr getpwname 3
 423 to retrieve a record,
 424 the lock will be lost because
 425 .Xr getpwname 3
 426 opens, reads, and closes the password database.
 427 The database close will release all locks that the process has
 428 associated with the database, even if the library routine never
 429 requested a lock on the database.
 430 Another minor semantic problem with this interface is that
 431 locks are not inherited by a child process created using the
 432 .Xr fork 2
 433 function.
 434 The
 435 .Xr flock 2
 436 interface has much more rational last close semantics and
 437 allows locks to be inherited by child processes.
 438 .Xr Flock 2
 439 is recommended for applications that want to ensure the integrity
 440 of their locks when using library routines or wish to pass locks
 441 to their children.
 442 Note that
 443 .Xr flock 2
 444 and
 445 .Xr fcntl 2
 446 locks may be safely used concurrently.
 447 .Pp
 448 All locks associated with a file for a given process are
 449 removed when the process terminates.
 450 .Pp
 451 A potential for deadlock occurs if a process controlling a locked region
 452 is put to sleep by attempting to lock the locked region of another process.
 453 This implementation detects that sleeping until a locked region is unlocked
 454 would cause a deadlock and fails with an
 455 .Er EDEADLK
 456 error.
 457 .Pp
 458 The
 459 .Dv F_PREALLOCATE
 460 command operates on the following structure:
 461 .ne 7v
 462 .Bd -literal
 463         typedef struct fstore {
 464             u_int32_t fst_flags;      /* IN: flags word */
 465             int       fst_posmode;    /* IN: indicates offset field */
 466             off_t     fst_offset;     /* IN: start of the region */
 467             off_t     fst_length;     /* IN: size of the region */
 468             off_t     fst_bytesalloc; /* OUT: number of bytes allocated */
 469         } fstore_t;
 470 .Ed
 471 .Pp
 472 The flags (fst_flags) for the
 473 .Dv F_PREALLOCATE
 474 command are as follows:
 475 .Bl -tag -width F_ALLOCATECONTIGX -offset indent
 476 .It Dv F_ALLOCATECONTIG
 477 Allocate contiguous space.
 478 .It Dv F_ALLOCATEALL
 479 Allocate all requested space or no space at all.
 480 .El
 481 .Pp
 482 The position modes (fst_posmode) for the
 483 .Dv F_PREALLOCATE
 484 command indicate how to use the offset field.
 485 The modes are as follows:
 486 .Bl -tag -width F_PEOFPOSMODEX -offset indent
 487 .It Dv F_PEOFPOSMODE
 488 Allocate from the physical end of file.
 489 .It Dv F_VOLPOSMODE
 490 Allocate from the volume offset.
 491 .El
 492 .Pp
 493 The
 494 .Dv F_RDADVISE
 495 command operates on the following structure
 496 which holds information passed from the
 497 user to the system:
 498 .ne 7v
 499 .Bd -literal
 500         struct radvisory {
 501            off_t   ra_offset;  /* offset into the file */
 502            int     ra_count;   /* size of the read     */
 503         };
 504 .Ed
 505 .Pp
 506 The
 507 .Dv F_READBOOTSTRAP and F_WRITEBOOTSTRAP
 508 commands operate on the following structure.
 509 .ne 7v
 510 .Bd -literal
 511         typedef struct fbootstraptransfer {
 512             off_t fbt_offset;       /* IN: offset to start read/write */
 513             size_t fbt_length;      /* IN: number of bytes to transfer */
 514             void *fbt_buffer;       /* IN: buffer to be read/written */
 515         } fbootstraptransfer_t;
 516 .Ed
 517 .Pp
 518 The
 519 .Dv F_LOG2PHYS
 520 command operates on the following structure:
 521 .ne 7v
 522 .Bd -literal
 523         struct log2phys {
 524             u_int32_t l2p_flags;        /* unused so far */
 525             off_t     l2p_contigbytes;  /* unused so far */
 526             off_t     l2p_devoffset;    /* bytes into device */
 527         };
 528 .Ed
 529 .Pp
 530 The
 531 .Dv F_LOG2PHYS_EXT
 532 command operates on the same structure as F_LOG2PHYS but treats it as an in/out:
 533 .ne 7v
 534 .Bd -literal
 535         struct log2phys {
 536             u_int32_t l2p_flags;        /* unused so far */
 537             off_t     l2p_contigbytes;  /* IN: number of bytes to be queried;
 538                                            OUT: number of contiguous bytes allocated at this position */
 539             off_t     l2p_devoffset;    /* IN: bytes into file;
 540                                            OUT: bytes into device */
 541         };
 542 .Ed
 543 .Pp
 544 If
 545 .Fa fildes
 546 is a socket, then the
 547 .Dv F_SETNOSIGPIPE
 548 and
 549 .Dv F_GETNOSIGPIPE
 550 commands are directly analogous, and fully interoperate with the
 551 .Dv SO_NOSIGPIPE
 552 option of
 553 .Xr setsockopt 2
 554 and
 555 .Xr getsockopt 2
 556 respectively.
 557 .Sh RETURN VALUES
 558 Upon successful completion, the value returned depends on
 559 .Fa cmd
 560 as follows:
 561 .Bl -tag -width F_GETOWNX -offset indent
 562 .It Dv F_DUPFD
 563 A new file descriptor.
 564 .It Dv F_GETFD
 565 Value of flag (only the low-order bit is defined).
 566 .It Dv F_GETFL
 567 Value of flags.
 568 .It Dv F_GETOWN
 569 Value of file descriptor owner.
 570 .It other
 571 Value other than -1.
 572 .El
 573 .Pp
 574 Otherwise, a value of -1 is returned and
 575 .Va errno
 576 is set to indicate the error.
 577 .Sh ERRORS
 578 The
 579 .Fn fcntl
 580 system call will fail if:
 581 .Bl -tag -width Er
 582 .\" ==========
 583 .It Bq Er EAGAIN
 584 The argument
 585 .Fa cmd
 586 is
 587 .Dv F_SETLK ,
 588 the type of lock
 589 .Fa (l_type)
 590 is a shared lock
 591 .Dv (F_RDLCK)
 592 or exclusive lock
 593 .Dv (F_WRLCK) ,
 594 and the segment of a file to be locked is already
 595 exclusive-locked by another process;
 596 or the type is an exclusive lock and some portion of the
 597 segment of a file to be locked is already shared-locked or
 598 exclusive-locked by another process.
 599 .It Bq Er EACCESS
 600 The argument
 601 .Fa cmd
 602 is either
 603 .Dv F_SETSIZE
 604 or
 605 .Dv F_WRITEBOOTSTRAP
 606 and the calling process does not have root privileges.
 607 .\" ==========
 608 .It Bq Er EBADF
 609 .Fa Fildes
 610 is not a valid open file descriptor.
 611 .Pp
 612 The argument
 613 .Fa cmd
 614 is
 615 .Dv F_SETLK
 616 or
 617 .Dv F_SETLKW ,
 618 the type of lock
 619 .Fa (l_type)
 620 is a shared lock
 621 .Dv (F_RDLCK) ,
 622 and
 623 .Fa fildes
 624 is not a valid file descriptor open for reading.
 625 .Pp
 626 The argument
 627 .Fa cmd
 628 is
 629 .Dv F_SETLK
 630 or
 631 .Dv F_SETLKW ,
 632 the type of lock
 633 .Fa (l_type)
 634 is an exclusive lock
 635 .Dv (F_WRLCK) ,
 636 and
 637 .Fa fildes
 638 is not a valid file descriptor open for writing.
 639 .Pp
 640 The argument
 641 .Fa cmd
 642 is
 643 .Dv F_PREALLOCATE
 644 and the calling process does not have
 645 file write permission.
 646 .Pp
 647 The argument
 648 .Fa cmd
 649 is
 650 .Dv F_LOG2PHYS
 651 or
 652 .Dv F_LOG2PHYS_EXT
 653 and
 654 .Fa fildes
 655 is not a valid file descriptor open for reading.
 656 .\" ==========
 657 .It Bq Er EDEADLK
 658 The argument
 659 .Fa cmd
 660 is
 661 .Dv F_SETLKW ,
 662 and a deadlock condition was detected.
 663 .\" ==========
 664 .It Bq Er EINTR
 665 The argument
 666 .Fa cmd
 667 is
 668 .Dv F_SETLKW ,
 669 and the function was interrupted by a signal.
 670 .\" ==========
 671 .It Bq Er EINVAL
 672 .Fa Cmd
 673 is
 674 .Dv F_DUPFD
 675 and
 676 .Fa arg
 677 is negative or greater than the maximum allowable number
 678 (see
 679 .Xr getdtablesize 2 ) .
 680 .Pp
 681 The argument
 682 .Fa cmd
 683 is
 684 .Dv F_GETLK ,
 685 .Dv F_SETLK ,
 686 or
 687 .Dv F_SETLKW
 688 and the data to which
 689 .Fa arg
 690 points is not valid, or
 691 .Fa fildes
 692 refers to a file that does not support locking.
 693 .Pp
 694 The argument
 695 .Fa cmd
 696 is
 697 .Dv F_PREALLOCATE
 698 and the
 699 .Fa fst_posmode
 700 is not a valid mode,
 701 or when
 702 .Dv F_PEOFPOSMODE
 703 is set and
 704 .Fa fst_offset
 705 is a non-zero value,
 706 or when
 707 .Dv F_VOLPOSMODE
 708 is set and
 709 .Fa fst_offset
 710 is a negative or zero value.
 711 .Pp
 712 The argument
 713 .Fa cmd
 714 is either
 715 .Dv F_READBOOTSTRAP
 716 or
 717 .Dv F_WRITEBOOTSTRAP
 718 and the operation was attempted on a non-HFS disk type.
 719 .\" ==========
 720 .It Bq Er EMFILE
 721 .Fa Cmd
 722 is
 723 .Dv F_DUPFD
 724 and the maximum allowed number of file descriptors are currently
 725 open.
 726 .\" ==========
 727 .It Bq Er EMFILE
 728 The argument
 729 .Fa cmd
 730 is
 731 .Dv F_DUPED
 732 and the maximum number of file descriptors permitted for the
 733 process are already in use,
 734 or no file descriptors greater than or equal to
 735 .Fa arg
 736 are available.
 737 .\" ==========
 738 .It Bq Er ENOLCK
 739 The argument
 740 .Fa cmd
 741 is
 742 .Dv F_SETLK
 743 or
 744 .Dv F_SETLKW ,
 745 and satisfying the lock or unlock request would result in the
 746 number of locked regions in the system exceeding a system-imposed limit.
 747 .\" ==========
 748 .It Bq Er EOVERFLOW
 749 A return value would overflow its representation.
 750 For example,
 751 .Fa cmd
 752 is F_GETLK, F_SETLK, or F_SETLKW
 753 and the smallest (or, if l_len is non-zero, the largest) offset
 754 of a byte in the requested segment
 755 will not fit in an object of type off_t.
 756 .\" ==========
 757 .It Bq Er ESRCH
 758 .Fa Cmd
 759 is
 760 .Dv F_SETOWN
 761 and
 762 the process ID given as argument is not in use.
 763 .El
 764 .Sh SEE ALSO
 765 .Xr close 2 ,
 766 .Xr execve 2 ,
 767 .Xr flock 2 ,
 768 .Xr getdtablesize 2 ,
 769 .Xr open 2 ,
 770 .Xr pipe 2 ,
 771 .Xr socket 2 ,
 772 .Xr setsockopt 2 ,
 773 .Xr sigaction 3
 774 .Sh HISTORY
 775 The
 776 .Fn fcntl
 777 function call appeared in
 778 .Bx 4.2 .