lib/libc/sys/fcntl.2

   1 .\" Copyright (c) 1983, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)fcntl.2     8.2 (Berkeley) 1/12/94
  29 .\"
  30 .Dd December 7, 2021
  31 .Dt FCNTL 2
  32 .Os
  33 .Sh NAME
  34 .Nm fcntl
  35 .Nd file control
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In fcntl.h
  40 .Ft int
  41 .Fn fcntl "int fd" "int cmd" "..."
  42 .Sh DESCRIPTION
  43 The
  44 .Fn fcntl
  45 system call provides for control over descriptors.
  46 The argument
  47 .Fa fd
  48 is a descriptor to be operated on by
  49 .Fa cmd
  50 as described below.
  51 Depending on the value of
  52 .Fa cmd ,
  53 .Fn fcntl
  54 can take an additional third argument
  55 .Fa arg .
  56 Unless otherwise noted below for a specific operation,
  57 .Fa arg
  58 has type
  59 .Vt int .
  60 .Bl -tag -width F_DUP2FD_CLOEXEC
  61 .It Dv F_DUPFD
  62 Return a new descriptor as follows:
  63 .Pp
  64 .Bl -bullet -compact -offset 4n
  65 .It
  66 Lowest numbered available descriptor greater than or equal to
  67 .Fa arg .
  68 .It
  69 Same object references as the original descriptor.
  70 .It
  71 New descriptor shares the same file offset if the object
  72 was a file.
  73 .It
  74 Same access mode (read, write or read/write).
  75 .It
  76 Same file status flags (i.e., both file descriptors
  77 share the same file status flags).
  78 .It
  79 The close-on-exec flag
  80 .Dv FD_CLOEXEC
  81 associated with the new file descriptor is cleared, so the file descriptor is
  82 to remain open across
  83 .Xr execve 2
  84 system calls.
  85 .El
  86 .It Dv F_DUPFD_CLOEXEC
  87 Like
  88 .Dv F_DUPFD ,
  89 but the
  90 .Dv FD_CLOEXEC
  91 flag associated with the new file descriptor is set, so the file descriptor
  92 is closed when
  93 .Xr execve 2
  94 system call executes.
  95 .It Dv F_DUP2FD
  96 It is functionally equivalent to
  97 .Bd -literal -offset indent
  98 dup2(fd, arg)
  99 .Ed
 100 .It Dv F_DUP2FD_CLOEXEC
 101 Like
 102 .Dv F_DUP2FD ,
 103 but the
 104 .Dv FD_CLOEXEC
 105 flag associated with the new file descriptor is set.
 106 .Pp
 107 The
 108 .Dv F_DUP2FD
 109 and
 110 .Dv F_DUP2FD_CLOEXEC
 111 constants are not portable, so they should not be used if
 112 portability is needed.
 113 Use
 114 .Fn dup2
 115 instead of
 116 .Dv F_DUP2FD .
 117 .It Dv F_GETFD
 118 Get the close-on-exec flag associated with the file descriptor
 119 .Fa fd
 120 as
 121 .Dv FD_CLOEXEC .
 122 If the returned value ANDed with
 123 .Dv FD_CLOEXEC
 124 is 0,
 125 the file will remain open across
 126 .Fn exec ,
 127 otherwise the file will be closed upon execution of
 128 .Fn exec
 129 .Fa ( arg
 130 is ignored).
 131 .It Dv F_SETFD
 132 Set the close-on-exec flag associated with
 133 .Fa fd
 134 to
 135 .Fa arg ,
 136 where
 137 .Fa arg
 138 is either 0 or
 139 .Dv FD_CLOEXEC ,
 140 as described above.
 141 .It Dv F_GETFL
 142 Get descriptor status flags, as described below
 143 .Fa ( arg
 144 is ignored).
 145 .It Dv F_SETFL
 146 Set descriptor status flags to
 147 .Fa arg .
 148 .It Dv F_GETOWN
 149 Get the process ID or process group
 150 currently receiving
 151 .Dv SIGIO
 152 and
 153 .Dv SIGURG
 154 signals; process groups are returned
 155 as negative values
 156 .Fa ( arg
 157 is ignored).
 158 .It Dv F_SETOWN
 159 Set the process or process group
 160 to receive
 161 .Dv SIGIO
 162 and
 163 .Dv SIGURG
 164 signals;
 165 process groups are specified by supplying
 166 .Fa arg
 167 as negative, otherwise
 168 .Fa arg
 169 is interpreted as a process ID.
 170 .It Dv F_READAHEAD
 171 Set or clear the read ahead amount for sequential access to the third
 172 argument,
 173 .Fa arg ,
 174 which is rounded up to the nearest block size.
 175 A zero value in
 176 .Fa arg
 177 turns off read ahead, a negative value restores the system default.
 178 .It Dv F_RDAHEAD
 179 Equivalent to Darwin counterpart which sets read ahead amount of 128KB
 180 when the third argument,
 181 .Fa arg
 182 is non-zero.
 183 A zero value in
 184 .Fa arg
 185 turns off read ahead.
 186 .It Dv F_ADD_SEALS
 187 Add seals to the file as described below, if the underlying filesystem supports
 188 seals.
 189 .It Dv F_GET_SEALS
 190 Get seals associated with the file, if the underlying filesystem supports seals.
 191 .It Dv F_ISUNIONSTACK
 192 Check if the vnode is part of a union stack (either the "union" flag from
 193 .Xr mount 2
 194 or unionfs).
 195 This is a hack not intended to be used outside of libc.
 196 .It Dv F_KINFO
 197 Fills a
 198 .Vt struct kinfo_file
 199 for the file referenced by the specified file descriptor.
 200 The
 201 .Fa arg
 202 argument should point to the storage for
 203 .Vt struct kinfo_file .
 204 The
 205 .Va kf_structsize
 206 member of the passed structure must be initialized with the sizeof of
 207 .Vt struct kinfo_file ,
 208 to allow for the interface versioning and evolution.
 209 .El
 210 .Pp
 211 The flags for the
 212 .Dv F_GETFL
 213 and
 214 .Dv F_SETFL
 215 commands are as follows:
 216 .Bl -tag -width O_NONBLOCKX
 217 .It Dv O_NONBLOCK
 218 Non-blocking I/O; if no data is available to a
 219 .Xr read 2
 220 system call, or if a
 221 .Xr write 2
 222 operation would block,
 223 the read or write call returns -1 with the error
 224 .Er EAGAIN .
 225 .It Dv O_APPEND
 226 Force each write to append at the end of file;
 227 corresponds to the
 228 .Dv O_APPEND
 229 flag of
 230 .Xr open 2 .
 231 .It Dv O_DIRECT
 232 Minimize or eliminate the cache effects of reading and writing.
 233 The system
 234 will attempt to avoid caching the data you read or write.
 235 If it cannot
 236 avoid caching the data, it will minimize the impact the data has on the cache.
 237 Use of this flag can drastically reduce performance if not used with care.
 238 .It Dv O_ASYNC
 239 Enable the
 240 .Dv SIGIO
 241 signal to be sent to the process group
 242 when I/O is possible, e.g.,
 243 upon availability of data to be read.
 244 .It Dv O_SYNC
 245 Enable synchronous writes.
 246 Corresponds to the
 247 .Dv O_SYNC
 248 flag of
 249 .Xr open 2 .
 250 .Dv O_FSYNC
 251 is an historical synonym for
 252 .Dv O_SYNC .
 253 .It Dv O_DSYNC
 254 Enable synchronous data writes.
 255 Corresponds to the
 256 .Dv O_DSYNC
 257 flag of
 258 .Xr open 2 .
 259 .El
 260 .Pp
 261 The seals that may be applied with
 262 .Dv F_ADD_SEALS
 263 are as follows:
 264 .Bl -tag -width F_SEAL_SHRINK
 265 .It Dv F_SEAL_SEAL
 266 Prevent any further seals from being applied to the file.
 267 .It Dv F_SEAL_SHRINK
 268 Prevent the file from being shrunk with
 269 .Xr ftruncate 2 .
 270 .It Dv F_SEAL_GROW
 271 Prevent the file from being enlarged with
 272 .Xr ftruncate 2 .
 273 .It Dv F_SEAL_WRITE
 274 Prevent any further
 275 .Xr write 2
 276 calls to the file.
 277 Any writes in progress will finish before
 278 .Fn fcntl
 279 returns.
 280 If any writeable mappings exist, F_ADD_SEALS will fail and return
 281 .Dv EBUSY .
 282 .El
 283 .Pp
 284 Seals are on a per-inode basis and require support by the underlying filesystem.
 285 If the underlying filesystem does not support seals,
 286 .Dv F_ADD_SEALS
 287 and
 288 .Dv F_GET_SEALS
 289 will fail and return
 290 .Dv EINVAL .
 291 .Pp
 292 Several operations are available for doing advisory file locking;
 293 they all operate on the following structure:
 294 .Bd -literal
 295 struct flock {
 296         off_t   l_start;        /* starting offset */
 297         off_t   l_len;          /* len = 0 means until end of file */
 298         pid_t   l_pid;          /* lock owner */
 299         short   l_type;         /* lock type: read/write, etc. */
 300         short   l_whence;       /* type of l_start */
 301         int     l_sysid;        /* remote system id or zero for local */
 302 };
 303 .Ed
 304 These advisory file locking operations take a pointer to
 305 .Vt struct flock
 306 as the third argument
 307 .Fa arg .
 308 The commands available for advisory record locking are as follows:
 309 .Bl -tag -width F_SETLKWX
 310 .It Dv F_GETLK
 311 Get the first lock that blocks the lock description pointed to by the
 312 third argument,
 313 .Fa arg ,
 314 taken as a pointer to a
 315 .Fa "struct flock"
 316 (see above).
 317 The information retrieved overwrites the information passed to
 318 .Fn fcntl
 319 in the
 320 .Fa flock
 321 structure.
 322 If no lock is found that would prevent this lock from being created,
 323 the structure is left unchanged by this system call except for the
 324 lock type which is set to
 325 .Dv F_UNLCK .
 326 .It Dv F_SETLK
 327 Set or clear a file segment lock according to the lock description
 328 pointed to by the third argument,
 329 .Fa arg ,
 330 taken as a pointer to a
 331 .Fa "struct flock"
 332 (see above).
 333 .Dv F_SETLK
 334 is used to establish shared (or read) locks
 335 .Pq Dv F_RDLCK
 336 or exclusive (or write) locks,
 337 .Pq Dv F_WRLCK ,
 338 as well as remove either type of lock
 339 .Pq Dv F_UNLCK .
 340 If a shared or exclusive lock cannot be set,
 341 .Fn fcntl
 342 returns immediately with
 343 .Er EAGAIN .
 344 .It Dv F_SETLKW
 345 This command is the same as
 346 .Dv F_SETLK
 347 except that if a shared or exclusive lock is blocked by other locks,
 348 the process waits until the request can be satisfied.
 349 If a signal that is to be caught is received while
 350 .Fn fcntl
 351 is waiting for a region, the
 352 .Fn fcntl
 353 will be interrupted if the signal handler has not specified the
 354 .Dv SA_RESTART
 355 (see
 356 .Xr sigaction 2 ) .
 357 .El
 358 .Pp
 359 When a shared lock has been set on a segment of a file,
 360 other processes can set shared locks on that segment
 361 or a portion of it.
 362 A shared lock prevents any other process from setting an exclusive
 363 lock on any portion of the protected area.
 364 A request for a shared lock fails if the file descriptor was not
 365 opened with read access.
 366 .Pp
 367 An exclusive lock prevents any other process from setting a shared lock or
 368 an exclusive lock on any portion of the protected area.
 369 A request for an exclusive lock fails if the file was not
 370 opened with write access.
 371 .Pp
 372 The value of
 373 .Fa l_whence
 374 is
 375 .Dv SEEK_SET ,
 376 .Dv SEEK_CUR ,
 377 or
 378 .Dv SEEK_END
 379 to indicate that the relative offset,
 380 .Fa l_start
 381 bytes, will be measured from the start of the file,
 382 current position, or end of the file, respectively.
 383 The value of
 384 .Fa l_len
 385 is the number of consecutive bytes to be locked.
 386 If
 387 .Fa l_len
 388 is negative,
 389 .Fa l_start
 390 means end edge of the region.
 391 The
 392 .Fa l_pid
 393 and
 394 .Fa l_sysid
 395 fields are only used with
 396 .Dv F_GETLK
 397 to return the process ID of the process holding a blocking lock and
 398 the system ID of the system that owns that process.
 399 Locks created by the local system will have a system ID of zero.
 400 After a successful
 401 .Dv F_GETLK
 402 request, the value of
 403 .Fa l_whence
 404 is
 405 .Dv SEEK_SET .
 406 .Pp
 407 Locks may start and extend beyond the current end of a file,
 408 but may not start or extend before the beginning of the file.
 409 A lock is set to extend to the largest possible value of the
 410 file offset for that file if
 411 .Fa l_len
 412 is set to zero.
 413 If
 414 .Fa l_whence
 415 and
 416 .Fa l_start
 417 point to the beginning of the file, and
 418 .Fa l_len
 419 is zero, the entire file is locked.
 420 If an application wishes only to do entire file locking, the
 421 .Xr flock 2
 422 system call is much more efficient.
 423 .Pp
 424 There is at most one type of lock set for each byte in the file.
 425 Before a successful return from an
 426 .Dv F_SETLK
 427 or an
 428 .Dv F_SETLKW
 429 request when the calling process has previously existing locks
 430 on bytes in the region specified by the request,
 431 the previous lock type for each byte in the specified
 432 region is replaced by the new lock type.
 433 As specified above under the descriptions
 434 of shared locks and exclusive locks, an
 435 .Dv F_SETLK
 436 or an
 437 .Dv F_SETLKW
 438 request fails or blocks respectively when another process has existing
 439 locks on bytes in the specified region and the type of any of those
 440 locks conflicts with the type specified in the request.
 441 .Pp
 442 The queuing for
 443 .Dv F_SETLKW
 444 requests on local files is fair;
 445 that is, while the thread is blocked,
 446 subsequent requests conflicting with its requests will not be granted,
 447 even if these requests do not conflict with existing locks.
 448 .Pp
 449 This interface follows the completely stupid semantics of System V and
 450 .St -p1003.1-88
 451 that require that all locks associated with a file for a given process are
 452 removed when
 453 .Em any
 454 file descriptor for that file is closed by that process.
 455 This semantic means that applications must be aware of any files that
 456 a subroutine library may access.
 457 For example if an application for updating the password file locks the
 458 password file database while making the update, and then calls
 459 .Xr getpwnam 3
 460 to retrieve a record,
 461 the lock will be lost because
 462 .Xr getpwnam 3
 463 opens, reads, and closes the password database.
 464 The database close will release all locks that the process has
 465 associated with the database, even if the library routine never
 466 requested a lock on the database.
 467 Another minor semantic problem with this interface is that
 468 locks are not inherited by a child process created using the
 469 .Xr fork 2
 470 system call.
 471 The
 472 .Xr flock 2
 473 interface has much more rational last close semantics and
 474 allows locks to be inherited by child processes.
 475 The
 476 .Xr flock 2
 477 system call is recommended for applications that want to ensure the integrity
 478 of their locks when using library routines or wish to pass locks
 479 to their children.
 480 .Pp
 481 The
 482 .Fn fcntl ,
 483 .Xr flock 2 ,
 484 and
 485 .Xr lockf 3
 486 locks are compatible.
 487 Processes using different locking interfaces can cooperate
 488 over the same file safely.
 489 However, only one of such interfaces should be used within
 490 the same process.
 491 If a file is locked by a process through
 492 .Xr flock 2 ,
 493 any record within the file will be seen as locked
 494 from the viewpoint of another process using
 495 .Fn fcntl
 496 or
 497 .Xr lockf 3 ,
 498 and vice versa.
 499 Note that
 500 .Fn fcntl F_GETLK
 501 returns \-1 in
 502 .Fa l_pid
 503 if the process holding a blocking lock previously locked the
 504 file descriptor by
 505 .Xr flock 2 .
 506 .Pp
 507 All locks associated with a file for a given process are
 508 removed when the process terminates.
 509 .Pp
 510 All locks obtained before a call to
 511 .Xr execve 2
 512 remain in effect until the new program releases them.
 513 If the new program does not know about the locks, they will not be
 514 released until the program exits.
 515 .Pp
 516 A potential for deadlock occurs if a process controlling a locked region
 517 is put to sleep by attempting to lock the locked region of another process.
 518 This implementation detects that sleeping until a locked region is unlocked
 519 would cause a deadlock and fails with an
 520 .Er EDEADLK
 521 error.
 522 .Sh RETURN VALUES
 523 Upon successful completion, the value returned depends on
 524 .Fa cmd
 525 as follows:
 526 .Bl -tag -width F_GETOWNX -offset indent
 527 .It Dv F_DUPFD
 528 A new file descriptor.
 529 .It Dv F_DUP2FD
 530 A file descriptor equal to
 531 .Fa arg .
 532 .It Dv F_GETFD
 533 Value of flag (only the low-order bit is defined).
 534 .It Dv F_GETFL
 535 Value of flags.
 536 .It Dv F_GETOWN
 537 Value of file descriptor owner.
 538 .It other
 539 Value other than -1.
 540 .El
 541 .Pp
 542 Otherwise, a value of -1 is returned and
 543 .Va errno
 544 is set to indicate the error.
 545 .Sh ERRORS
 546 The
 547 .Fn fcntl
 548 system call will fail if:
 549 .Bl -tag -width Er
 550 .It Bq Er EAGAIN
 551 The argument
 552 .Fa cmd
 553 is
 554 .Dv F_SETLK ,
 555 the type of lock
 556 .Pq Fa l_type
 557 is a shared lock
 558 .Pq Dv F_RDLCK
 559 or exclusive lock
 560 .Pq Dv F_WRLCK ,
 561 and the segment of a file to be locked is already
 562 exclusive-locked by another process;
 563 or the type is an exclusive lock and some portion of the
 564 segment of a file to be locked is already shared-locked or
 565 exclusive-locked by another process.
 566 .It Bq Er EBADF
 567 The
 568 .Fa fd
 569 argument
 570 is not a valid open file descriptor.
 571 .Pp
 572 The argument
 573 .Fa cmd
 574 is
 575 .Dv F_DUP2FD ,
 576 and
 577 .Fa arg
 578 is not a valid file descriptor.
 579 .Pp
 580 The argument
 581 .Fa cmd
 582 is
 583 .Dv F_SETLK
 584 or
 585 .Dv F_SETLKW ,
 586 the type of lock
 587 .Pq Fa l_type
 588 is a shared lock
 589 .Pq Dv F_RDLCK ,
 590 and
 591 .Fa fd
 592 is not a valid file descriptor open for reading.
 593 .Pp
 594 The argument
 595 .Fa cmd
 596 is
 597 .Dv F_SETLK
 598 or
 599 .Dv F_SETLKW ,
 600 the type of lock
 601 .Pq Fa l_type
 602 is an exclusive lock
 603 .Pq Dv F_WRLCK ,
 604 and
 605 .Fa fd
 606 is not a valid file descriptor open for writing.
 607 .It Bq Er EBUSY
 608 The argument
 609 .Fa cmd
 610 is
 611 .Dv F_ADD_SEALS ,
 612 attempting to set
 613 .Dv F_SEAL_WRITE ,
 614 and writeable mappings of the file exist.
 615 .It Bq Er EDEADLK
 616 The argument
 617 .Fa cmd
 618 is
 619 .Dv F_SETLKW ,
 620 and a deadlock condition was detected.
 621 .It Bq Er EINTR
 622 The argument
 623 .Fa cmd
 624 is
 625 .Dv F_SETLKW ,
 626 and the system call was interrupted by a signal.
 627 .It Bq Er EINVAL
 628 The
 629 .Fa cmd
 630 argument
 631 is
 632 .Dv F_DUPFD
 633 and
 634 .Fa arg
 635 is negative or greater than the maximum allowable number
 636 (see
 637 .Xr getdtablesize 2 ) .
 638 .Pp
 639 The argument
 640 .Fa cmd
 641 is
 642 .Dv F_GETLK ,
 643 .Dv F_SETLK
 644 or
 645 .Dv F_SETLKW
 646 and the data to which
 647 .Fa arg
 648 points is not valid.
 649 .Pp
 650 The argument
 651 .Fa cmd
 652 is
 653 .Dv F_ADD_SEALS
 654 or
 655 .Dv F_GET_SEALS ,
 656 and the underlying filesystem does not support sealing.
 657 .Pp
 658 The argument
 659 .Fa cmd
 660 is invalid.
 661 .It Bq Er EMFILE
 662 The argument
 663 .Fa cmd
 664 is
 665 .Dv F_DUPFD
 666 and the maximum number of file descriptors permitted for the
 667 process are already in use,
 668 or no file descriptors greater than or equal to
 669 .Fa arg
 670 are available.
 671 .It Bq Er ENOTTY
 672 The
 673 .Fa fd
 674 argument is not a valid file descriptor for the requested operation.
 675 This may be the case if
 676 .Fa fd
 677 is a device node, or a descriptor returned by
 678 .Xr kqueue 2 .
 679 .It Bq Er ENOLCK
 680 The argument
 681 .Fa cmd
 682 is
 683 .Dv F_SETLK
 684 or
 685 .Dv F_SETLKW ,
 686 and satisfying the lock or unlock request would result in the
 687 number of locked regions in the system exceeding a system-imposed limit.
 688 .It Bq Er EOPNOTSUPP
 689 The argument
 690 .Fa cmd
 691 is
 692 .Dv F_GETLK ,
 693 .Dv F_SETLK
 694 or
 695 .Dv F_SETLKW
 696 and
 697 .Fa fd
 698 refers to a file for which locking is not supported.
 699 .It Bq Er EOVERFLOW
 700 The argument
 701 .Fa cmd
 702 is
 703 .Dv F_GETLK ,
 704 .Dv F_SETLK
 705 or
 706 .Dv F_SETLKW
 707 and an
 708 .Fa off_t
 709 calculation overflowed.
 710 .It Bq Er EPERM
 711 The
 712 .Fa cmd
 713 argument
 714 is
 715 .Dv F_SETOWN
 716 and
 717 the process ID or process group given as an argument is in a
 718 different session than the caller.
 719 .Pp
 720 The
 721 .Fa cmd
 722 argument
 723 is
 724 .Dv F_ADD_SEALS
 725 and the
 726 .Dv F_SEAL_SEAL
 727 seal has already been set.
 728 .It Bq Er ESRCH
 729 The
 730 .Fa cmd
 731 argument
 732 is
 733 .Dv F_SETOWN
 734 and
 735 the process ID given as argument is not in use.
 736 .El
 737 .Pp
 738 In addition, if
 739 .Fa fd
 740 refers to a descriptor open on a terminal device (as opposed to a
 741 descriptor open on a socket), a
 742 .Fa cmd
 743 of
 744 .Dv F_SETOWN
 745 can fail for the same reasons as in
 746 .Xr tcsetpgrp 3 ,
 747 and a
 748 .Fa cmd
 749 of
 750 .Dv F_GETOWN
 751 for the reasons as stated in
 752 .Xr tcgetpgrp 3 .
 753 .Sh SEE ALSO
 754 .Xr close 2 ,
 755 .Xr dup2 2 ,
 756 .Xr execve 2 ,
 757 .Xr flock 2 ,
 758 .Xr getdtablesize 2 ,
 759 .Xr open 2 ,
 760 .Xr sigaction 2 ,
 761 .Xr lockf 3 ,
 762 .Xr tcgetpgrp 3 ,
 763 .Xr tcsetpgrp 3
 764 .Sh STANDARDS
 765 The
 766 .Dv F_DUP2FD
 767 constant is non portable.
 768 It is provided for compatibility with AIX and Solaris.
 769 .Pp
 770 Per
 771 .St -susv4 ,
 772 a call with
 773 .Dv F_SETLKW
 774 should fail with
 775 .Bq Er EINTR
 776 after any caught signal
 777 and should continue waiting during thread suspension such as a stop signal.
 778 However, in this implementation a call with
 779 .Dv F_SETLKW
 780 is restarted after catching a signal with a
 781 .Dv SA_RESTART
 782 handler or a thread suspension such as a stop signal.
 783 .Sh HISTORY
 784 The
 785 .Fn fcntl
 786 system call appeared in
 787 .Bx 4.2 .
 788 .Pp
 789 The
 790 .Dv F_DUP2FD
 791 constant first appeared in
 792 .Fx 7.1 .