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 .\" 4. 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 .\" $FreeBSD$
  30 .\"
  31 .Dd Nov 15, 2018
  32 .Dt FCNTL 2
  33 .Os
  34 .Sh NAME
  35 .Nm fcntl
  36 .Nd file control
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In fcntl.h
  41 .Ft int
  42 .Fn fcntl "int fd" "int cmd" "..."
  43 .Sh DESCRIPTION
  44 The
  45 .Fn fcntl
  46 system call provides for control over descriptors.
  47 The argument
  48 .Fa fd
  49 is a descriptor to be operated on by
  50 .Fa cmd
  51 as described below.
  52 Depending on the value of
  53 .Fa cmd ,
  54 .Fn fcntl
  55 can take an additional third argument
  56 .Fa "int arg" .
  57 .Bl -tag -width F_DUP2FD_CLOEXEC
  58 .It Dv F_DUPFD
  59 Return a new descriptor as follows:
  60 .Pp
  61 .Bl -bullet -compact -offset 4n
  62 .It
  63 Lowest numbered available descriptor greater than or equal to
  64 .Fa arg .
  65 .It
  66 Same object references as the original descriptor.
  67 .It
  68 New descriptor shares the same file offset if the object
  69 was a file.
  70 .It
  71 Same access mode (read, write or read/write).
  72 .It
  73 Same file status flags (i.e., both file descriptors
  74 share the same file status flags).
  75 .It
  76 The close-on-exec flag
  77 .Dv FD_CLOEXEC
  78 associated with the new file descriptor is cleared, so the file descriptor is
  79 to remain open across
  80 .Xr execve 2
  81 system calls.
  82 .El
  83 .It Dv F_DUPFD_CLOEXEC
  84 Like
  85 .Dv F_DUPFD ,
  86 but the
  87 .Dv FD_CLOEXEC
  88 flag associated with the new file descriptor is set, so the file descriptor
  89 is closed when
  90 .Xr execve 2
  91 system call executes.
  92 .It Dv F_DUP2FD
  93 It is functionally equivalent to
  94 .Bd -literal -offset indent
  95 dup2(fd, arg)
  96 .Ed
  97 .It Dv F_DUP2FD_CLOEXEC
  98 Like
  99 .Dv F_DUP2FD ,
 100 but the
 101 .Dv FD_CLOEXEC
 102 flag associated with the new file descriptor is set.
 103 .Pp
 104 The
 105 .Dv F_DUP2FD
 106 and
 107 .Dv F_DUP2FD_CLOEXEC
 108 constants are not portable, so they should not be used if
 109 portability is needed.
 110 Use
 111 .Fn dup2
 112 instead of
 113 .Dv F_DUP2FD .
 114 .It Dv F_GETFD
 115 Get the close-on-exec flag associated with the file descriptor
 116 .Fa fd
 117 as
 118 .Dv FD_CLOEXEC .
 119 If the returned value ANDed with
 120 .Dv FD_CLOEXEC
 121 is 0,
 122 the file will remain open across
 123 .Fn exec ,
 124 otherwise the file will be closed upon execution of
 125 .Fn exec
 126 .Fa ( arg
 127 is ignored).
 128 .It Dv F_SETFD
 129 Set the close-on-exec flag associated with
 130 .Fa fd
 131 to
 132 .Fa arg ,
 133 where
 134 .Fa arg
 135 is either 0 or
 136 .Dv FD_CLOEXEC ,
 137 as described above.
 138 .It Dv F_GETFL
 139 Get descriptor status flags, as described below
 140 .Fa ( arg
 141 is ignored).
 142 .It Dv F_SETFL
 143 Set descriptor status flags to
 144 .Fa arg .
 145 .It Dv F_GETOWN
 146 Get the process ID or process group
 147 currently receiving
 148 .Dv SIGIO
 149 and
 150 .Dv SIGURG
 151 signals; process groups are returned
 152 as negative values
 153 .Fa ( arg
 154 is ignored).
 155 .It Dv F_SETOWN
 156 Set the process or process group
 157 to receive
 158 .Dv SIGIO
 159 and
 160 .Dv SIGURG
 161 signals;
 162 process groups are specified by supplying
 163 .Fa arg
 164 as negative, otherwise
 165 .Fa arg
 166 is interpreted as a process ID.
 167 .It Dv F_READAHEAD
 168 Set or clear the read ahead amount for sequential access to the third
 169 argument,
 170 .Fa arg ,
 171 which is rounded up to the nearest block size.
 172 A zero value in
 173 .Fa arg
 174 turns off read ahead, a negative value restores the system default.
 175 .It Dv F_RDAHEAD
 176 Equivalent to Darwin counterpart which sets read ahead amount of 128KB
 177 when the third argument,
 178 .Fa arg
 179 is non-zero.
 180 A zero value in
 181 .Fa arg
 182 turns off read ahead.
 183 .El
 184 .Pp
 185 The flags for the
 186 .Dv F_GETFL
 187 and
 188 .Dv F_SETFL
 189 flags are as follows:
 190 .Bl -tag -width O_NONBLOCKX
 191 .It Dv O_NONBLOCK
 192 Non-blocking I/O; if no data is available to a
 193 .Xr read 2
 194 system call, or if a
 195 .Xr write 2
 196 operation would block,
 197 the read or write call returns -1 with the error
 198 .Er EAGAIN .
 199 .It Dv O_APPEND
 200 Force each write to append at the end of file;
 201 corresponds to the
 202 .Dv O_APPEND
 203 flag of
 204 .Xr open 2 .
 205 .It Dv O_DIRECT
 206 Minimize or eliminate the cache effects of reading and writing.
 207 The system
 208 will attempt to avoid caching the data you read or write.
 209 If it cannot
 210 avoid caching the data, it will minimize the impact the data has on the cache.
 211 Use of this flag can drastically reduce performance if not used with care.
 212 .It Dv O_ASYNC
 213 Enable the
 214 .Dv SIGIO
 215 signal to be sent to the process group
 216 when I/O is possible, e.g.,
 217 upon availability of data to be read.
 218 .El
 219 .Pp
 220 Several commands are available for doing advisory file locking;
 221 they all operate on the following structure:
 222 .Bd -literal
 223 struct flock {
 224         off_t   l_start;        /* starting offset */
 225         off_t   l_len;          /* len = 0 means until end of file */
 226         pid_t   l_pid;          /* lock owner */
 227         short   l_type;         /* lock type: read/write, etc. */
 228         short   l_whence;       /* type of l_start */
 229         int     l_sysid;        /* remote system id or zero for local */
 230 };
 231 .Ed
 232 The commands available for advisory record locking are as follows:
 233 .Bl -tag -width F_SETLKWX
 234 .It Dv F_GETLK
 235 Get the first lock that blocks the lock description pointed to by the
 236 third argument,
 237 .Fa arg ,
 238 taken as a pointer to a
 239 .Fa "struct flock"
 240 (see above).
 241 The information retrieved overwrites the information passed to
 242 .Fn fcntl
 243 in the
 244 .Fa flock
 245 structure.
 246 If no lock is found that would prevent this lock from being created,
 247 the structure is left unchanged by this system call except for the
 248 lock type which is set to
 249 .Dv F_UNLCK .
 250 .It Dv F_SETLK
 251 Set or clear a file segment lock according to the lock description
 252 pointed to by the third argument,
 253 .Fa arg ,
 254 taken as a pointer to a
 255 .Fa "struct flock"
 256 (see above).
 257 .Dv F_SETLK
 258 is used to establish shared (or read) locks
 259 .Pq Dv F_RDLCK
 260 or exclusive (or write) locks,
 261 .Pq Dv F_WRLCK ,
 262 as well as remove either type of lock
 263 .Pq Dv F_UNLCK .
 264 If a shared or exclusive lock cannot be set,
 265 .Fn fcntl
 266 returns immediately with
 267 .Er EAGAIN .
 268 .It Dv F_SETLKW
 269 This command is the same as
 270 .Dv F_SETLK
 271 except that if a shared or exclusive lock is blocked by other locks,
 272 the process waits until the request can be satisfied.
 273 If a signal that is to be caught is received while
 274 .Fn fcntl
 275 is waiting for a region, the
 276 .Fn fcntl
 277 will be interrupted if the signal handler has not specified the
 278 .Dv SA_RESTART
 279 (see
 280 .Xr sigaction 2 ) .
 281 .El
 282 .Pp
 283 When a shared lock has been set on a segment of a file,
 284 other processes can set shared locks on that segment
 285 or a portion of it.
 286 A shared lock prevents any other process from setting an exclusive
 287 lock on any portion of the protected area.
 288 A request for a shared lock fails if the file descriptor was not
 289 opened with read access.
 290 .Pp
 291 An exclusive lock prevents any other process from setting a shared lock or
 292 an exclusive lock on any portion of the protected area.
 293 A request for an exclusive lock fails if the file was not
 294 opened with write access.
 295 .Pp
 296 The value of
 297 .Fa l_whence
 298 is
 299 .Dv SEEK_SET ,
 300 .Dv SEEK_CUR ,
 301 or
 302 .Dv SEEK_END
 303 to indicate that the relative offset,
 304 .Fa l_start
 305 bytes, will be measured from the start of the file,
 306 current position, or end of the file, respectively.
 307 The value of
 308 .Fa l_len
 309 is the number of consecutive bytes to be locked.
 310 If
 311 .Fa l_len
 312 is negative,
 313 .Fa l_start
 314 means end edge of the region.
 315 The
 316 .Fa l_pid
 317 and
 318 .Fa l_sysid
 319 fields are only used with
 320 .Dv F_GETLK
 321 to return the process ID of the process holding a blocking lock and
 322 the system ID of the system that owns that process.
 323 Locks created by the local system will have a system ID of zero.
 324 After a successful
 325 .Dv F_GETLK
 326 request, the value of
 327 .Fa l_whence
 328 is
 329 .Dv SEEK_SET .
 330 .Pp
 331 Locks may start and extend beyond the current end of a file,
 332 but may not start or extend before the beginning of the file.
 333 A lock is set to extend to the largest possible value of the
 334 file offset for that file if
 335 .Fa l_len
 336 is set to zero.
 337 If
 338 .Fa l_whence
 339 and
 340 .Fa l_start
 341 point to the beginning of the file, and
 342 .Fa l_len
 343 is zero, the entire file is locked.
 344 If an application wishes only to do entire file locking, the
 345 .Xr flock 2
 346 system call is much more efficient.
 347 .Pp
 348 There is at most one type of lock set for each byte in the file.
 349 Before a successful return from an
 350 .Dv F_SETLK
 351 or an
 352 .Dv F_SETLKW
 353 request when the calling process has previously existing locks
 354 on bytes in the region specified by the request,
 355 the previous lock type for each byte in the specified
 356 region is replaced by the new lock type.
 357 As specified above under the descriptions
 358 of shared locks and exclusive locks, an
 359 .Dv F_SETLK
 360 or an
 361 .Dv F_SETLKW
 362 request fails or blocks respectively when another process has existing
 363 locks on bytes in the specified region and the type of any of those
 364 locks conflicts with the type specified in the request.
 365 .Pp
 366 The queuing for
 367 .Dv F_SETLKW
 368 requests on local files is fair;
 369 that is, while the thread is blocked,
 370 subsequent requests conflicting with its requests will not be granted,
 371 even if these requests do not conflict with existing locks.
 372 .Pp
 373 This interface follows the completely stupid semantics of System V and
 374 .St -p1003.1-88
 375 that require that all locks associated with a file for a given process are
 376 removed when
 377 .Em any
 378 file descriptor for that file is closed by that process.
 379 This semantic means that applications must be aware of any files that
 380 a subroutine library may access.
 381 For example if an application for updating the password file locks the
 382 password file database while making the update, and then calls
 383 .Xr getpwnam 3
 384 to retrieve a record,
 385 the lock will be lost because
 386 .Xr getpwnam 3
 387 opens, reads, and closes the password database.
 388 The database close will release all locks that the process has
 389 associated with the database, even if the library routine never
 390 requested a lock on the database.
 391 Another minor semantic problem with this interface is that
 392 locks are not inherited by a child process created using the
 393 .Xr fork 2
 394 system call.
 395 The
 396 .Xr flock 2
 397 interface has much more rational last close semantics and
 398 allows locks to be inherited by child processes.
 399 The
 400 .Xr flock 2
 401 system call is recommended for applications that want to ensure the integrity
 402 of their locks when using library routines or wish to pass locks
 403 to their children.
 404 .Pp
 405 The
 406 .Fn fcntl ,
 407 .Xr flock 2 ,
 408 and
 409 .Xr lockf 3
 410 locks are compatible.
 411 Processes using different locking interfaces can cooperate
 412 over the same file safely.
 413 However, only one of such interfaces should be used within
 414 the same process.
 415 If a file is locked by a process through
 416 .Xr flock 2 ,
 417 any record within the file will be seen as locked
 418 from the viewpoint of another process using
 419 .Fn fcntl
 420 or
 421 .Xr lockf 3 ,
 422 and vice versa.
 423 Note that
 424 .Fn fcntl F_GETLK
 425 returns \-1 in
 426 .Fa l_pid
 427 if the process holding a blocking lock previously locked the
 428 file descriptor by
 429 .Xr flock 2 .
 430 .Pp
 431 All locks associated with a file for a given process are
 432 removed when the process terminates.
 433 .Pp
 434 All locks obtained before a call to
 435 .Xr execve 2
 436 remain in effect until the new program releases them.
 437 If the new program does not know about the locks, they will not be
 438 released until the program exits.
 439 .Pp
 440 A potential for deadlock occurs if a process controlling a locked region
 441 is put to sleep by attempting to lock the locked region of another process.
 442 This implementation detects that sleeping until a locked region is unlocked
 443 would cause a deadlock and fails with an
 444 .Er EDEADLK
 445 error.
 446 .Sh RETURN VALUES
 447 Upon successful completion, the value returned depends on
 448 .Fa cmd
 449 as follows:
 450 .Bl -tag -width F_GETOWNX -offset indent
 451 .It Dv F_DUPFD
 452 A new file descriptor.
 453 .It Dv F_DUP2FD
 454 A file descriptor equal to
 455 .Fa arg .
 456 .It Dv F_GETFD
 457 Value of flag (only the low-order bit is defined).
 458 .It Dv F_GETFL
 459 Value of flags.
 460 .It Dv F_GETOWN
 461 Value of file descriptor owner.
 462 .It other
 463 Value other than -1.
 464 .El
 465 .Pp
 466 Otherwise, a value of -1 is returned and
 467 .Va errno
 468 is set to indicate the error.
 469 .Sh ERRORS
 470 The
 471 .Fn fcntl
 472 system call will fail if:
 473 .Bl -tag -width Er
 474 .It Bq Er EAGAIN
 475 The argument
 476 .Fa cmd
 477 is
 478 .Dv F_SETLK ,
 479 the type of lock
 480 .Pq Fa l_type
 481 is a shared lock
 482 .Pq Dv F_RDLCK
 483 or exclusive lock
 484 .Pq Dv F_WRLCK ,
 485 and the segment of a file to be locked is already
 486 exclusive-locked by another process;
 487 or the type is an exclusive lock and some portion of the
 488 segment of a file to be locked is already shared-locked or
 489 exclusive-locked by another process.
 490 .It Bq Er EBADF
 491 The
 492 .Fa fd
 493 argument
 494 is not a valid open file descriptor.
 495 .Pp
 496 The argument
 497 .Fa cmd
 498 is
 499 .Dv F_DUP2FD ,
 500 and
 501 .Fa arg
 502 is not a valid file descriptor.
 503 .Pp
 504 The argument
 505 .Fa cmd
 506 is
 507 .Dv F_SETLK
 508 or
 509 .Dv F_SETLKW ,
 510 the type of lock
 511 .Pq Fa l_type
 512 is a shared lock
 513 .Pq Dv F_RDLCK ,
 514 and
 515 .Fa fd
 516 is not a valid file descriptor open for reading.
 517 .Pp
 518 The argument
 519 .Fa cmd
 520 is
 521 .Dv F_SETLK
 522 or
 523 .Dv F_SETLKW ,
 524 the type of lock
 525 .Pq Fa l_type
 526 is an exclusive lock
 527 .Pq Dv F_WRLCK ,
 528 and
 529 .Fa fd
 530 is not a valid file descriptor open for writing.
 531 .It Bq Er EDEADLK
 532 The argument
 533 .Fa cmd
 534 is
 535 .Dv F_SETLKW ,
 536 and a deadlock condition was detected.
 537 .It Bq Er EINTR
 538 The argument
 539 .Fa cmd
 540 is
 541 .Dv F_SETLKW ,
 542 and the system call was interrupted by a signal.
 543 .It Bq Er EINVAL
 544 The
 545 .Fa cmd
 546 argument
 547 is
 548 .Dv F_DUPFD
 549 and
 550 .Fa arg
 551 is negative or greater than the maximum allowable number
 552 (see
 553 .Xr getdtablesize 2 ) .
 554 .Pp
 555 The argument
 556 .Fa cmd
 557 is
 558 .Dv F_GETLK ,
 559 .Dv F_SETLK
 560 or
 561 .Dv F_SETLKW
 562 and the data to which
 563 .Fa arg
 564 points is not valid.
 565 .Pp
 566 The argument
 567 .Fa cmd
 568 is invalid.
 569 .It Bq Er EMFILE
 570 The argument
 571 .Fa cmd
 572 is
 573 .Dv F_DUPFD
 574 and the maximum number of file descriptors permitted for the
 575 process are already in use,
 576 or no file descriptors greater than or equal to
 577 .Fa arg
 578 are available.
 579 .It Bq Er ENOTTY
 580 The
 581 .Fa fd
 582 argument is not a valid file descriptor for the requested operation.
 583 This may be the case if
 584 .Fa fd
 585 is a device node, or a descriptor returned by
 586 .Xr kqueue 2 .
 587 .It Bq Er ENOLCK
 588 The argument
 589 .Fa cmd
 590 is
 591 .Dv F_SETLK
 592 or
 593 .Dv F_SETLKW ,
 594 and satisfying the lock or unlock request would result in the
 595 number of locked regions in the system exceeding a system-imposed limit.
 596 .It Bq Er EOPNOTSUPP
 597 The argument
 598 .Fa cmd
 599 is
 600 .Dv F_GETLK ,
 601 .Dv F_SETLK
 602 or
 603 .Dv F_SETLKW
 604 and
 605 .Fa fd
 606 refers to a file for which locking is not supported.
 607 .It Bq Er EOVERFLOW
 608 The argument
 609 .Fa cmd
 610 is
 611 .Dv F_GETLK ,
 612 .Dv F_SETLK
 613 or
 614 .Dv F_SETLKW
 615 and an
 616 .Fa off_t
 617 calculation overflowed.
 618 .It Bq Er EPERM
 619 The
 620 .Fa cmd
 621 argument
 622 is
 623 .Dv F_SETOWN
 624 and
 625 the process ID or process group given as an argument is in a
 626 different session than the caller.
 627 .It Bq Er ESRCH
 628 The
 629 .Fa cmd
 630 argument
 631 is
 632 .Dv F_SETOWN
 633 and
 634 the process ID given as argument is not in use.
 635 .El
 636 .Pp
 637 In addition, if
 638 .Fa fd
 639 refers to a descriptor open on a terminal device (as opposed to a
 640 descriptor open on a socket), a
 641 .Fa cmd
 642 of
 643 .Dv F_SETOWN
 644 can fail for the same reasons as in
 645 .Xr tcsetpgrp 3 ,
 646 and a
 647 .Fa cmd
 648 of
 649 .Dv F_GETOWN
 650 for the reasons as stated in
 651 .Xr tcgetpgrp 3 .
 652 .Sh SEE ALSO
 653 .Xr close 2 ,
 654 .Xr dup2 2 ,
 655 .Xr execve 2 ,
 656 .Xr flock 2 ,
 657 .Xr getdtablesize 2 ,
 658 .Xr open 2 ,
 659 .Xr sigaction 2 ,
 660 .Xr lockf 3 ,
 661 .Xr tcgetpgrp 3 ,
 662 .Xr tcsetpgrp 3
 663 .Sh STANDARDS
 664 The
 665 .Dv F_DUP2FD
 666 constant is non portable.
 667 It is provided for compatibility with AIX and Solaris.
 668 .Pp
 669 Per
 670 .St -susv4 ,
 671 a call with
 672 .Dv F_SETLKW
 673 should fail with
 674 .Bq Er EINTR
 675 after any caught signal
 676 and should continue waiting during thread suspension such as a stop signal.
 677 However, in this implementation a call with
 678 .Dv F_SETLKW
 679 is restarted after catching a signal with a
 680 .Dv SA_RESTART
 681 handler or a thread suspension such as a stop signal.
 682 .Sh HISTORY
 683 The
 684 .Fn fcntl
 685 system call appeared in
 686 .Bx 4.2 .
 687 .Pp
 688 The
 689 .Dv F_DUP2FD
 690 constant first appeared in
 691 .Fx 7.1 .