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 .\" $FreeBSD: src/lib/libc/sys/fcntl.2,v 1.16.2.13 2002/07/22 15:15:16 bde Exp $
  30 .\"
  31 .Dd March 30, 2021
  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 ".Dv 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_GETPATH
 168 Get the filesystem path associated with
 169 .Fa fd .
 170 At most
 171 .Dv MAXPATHLEN
 172 bytes will be written to the buffer provided in
 173 .Fa arg .
 174 .El
 175 .Pp
 176 The flags for the
 177 .Dv F_GETFL
 178 and
 179 .Dv F_SETFL
 180 flags are as follows:
 181 .Bl -tag -width O_NONBLOCKX
 182 .It Dv O_NONBLOCK
 183 Non-blocking I/O; if no data is available to a
 184 .Xr read 2
 185 system call, or if a
 186 .Xr write 2
 187 operation would block,
 188 the read or write call returns -1 with the error
 189 .Er EAGAIN .
 190 .It Dv O_APPEND
 191 Force each write to append at the end of file;
 192 corresponds to the
 193 .Dv O_APPEND
 194 flag of
 195 .Xr open 2 .
 196 .It Dv O_DIRECT
 197 Minimize or eliminate the cache effects of reading and writing.
 198 The system
 199 will attempt to avoid caching the data you read or write.
 200 If it cannot
 201 avoid caching the data, it will minimize the impact the data has on the cache.
 202 Use of this flag can drastically reduce performance if not used with care.
 203 .It Dv O_ASYNC
 204 Enable the
 205 .Dv SIGIO
 206 signal to be sent to the process group
 207 when I/O is possible, e.g.,
 208 upon availability of data to be read.
 209 .El
 210 .Pp
 211 Several commands are available for doing advisory file locking;
 212 they all operate on the following structure:
 213 .Bd -literal
 214 struct flock {
 215         off_t   l_start;        /* starting offset */
 216         off_t   l_len;          /* len = 0 means until end of file */
 217         pid_t   l_pid;          /* lock owner */
 218         short   l_type;         /* lock type: read/write, etc. */
 219         short   l_whence;       /* type of l_start */
 220 };
 221 .Ed
 222 The commands available for advisory record locking are as follows:
 223 .Bl -tag -width F_SETLKWX
 224 .It Dv F_GETLK
 225 Get the first lock that blocks the lock description pointed to by the
 226 third argument,
 227 .Fa arg ,
 228 taken as a pointer to a
 229 .Fa "struct flock"
 230 (see above).
 231 The information retrieved overwrites the information passed to
 232 .Fn fcntl
 233 in the
 234 .Fa flock
 235 structure.
 236 If no lock is found that would prevent this lock from being created,
 237 the structure is left unchanged by this system call except for the
 238 lock type which is set to
 239 .Dv F_UNLCK .
 240 .It Dv F_SETLK
 241 Set or clear a file segment lock according to the lock description
 242 pointed to by the third argument,
 243 .Fa arg ,
 244 taken as a pointer to a
 245 .Fa "struct flock"
 246 (see above).
 247 .Dv F_SETLK
 248 is used to establish shared (or read) locks
 249 .Pq Dv F_RDLCK
 250 or exclusive (or write) locks,
 251 .Pq Dv F_WRLCK ,
 252 as well as remove either type of lock
 253 .Pq Dv F_UNLCK .
 254 If a shared or exclusive lock cannot be set,
 255 .Fn fcntl
 256 returns immediately with
 257 .Er EAGAIN .
 258 .It Dv F_SETLKW
 259 This command is the same as
 260 .Dv F_SETLK
 261 except that if a shared or exclusive lock is blocked by other locks,
 262 the process waits until the request can be satisfied.
 263 If a signal that is to be caught is received while
 264 .Fn fcntl
 265 is waiting for a region, the
 266 .Fn fcntl
 267 will be interrupted if the signal handler has not specified the
 268 .Dv SA_RESTART
 269 (see
 270 .Xr sigaction 2 ) .
 271 .El
 272 .Pp
 273 When a shared lock has been set on a segment of a file,
 274 other processes can set shared locks on that segment
 275 or a portion of it.
 276 A shared lock prevents any other process from setting an exclusive
 277 lock on any portion of the protected area.
 278 A request for a shared lock fails if the file descriptor was not
 279 opened with read access.
 280 .Pp
 281 An exclusive lock prevents any other process from setting a shared lock or
 282 an exclusive lock on any portion of the protected area.
 283 A request for an exclusive lock fails if the file was not
 284 opened with write access.
 285 .Pp
 286 The value of
 287 .Fa l_whence
 288 is
 289 .Dv SEEK_SET ,
 290 .Dv SEEK_CUR ,
 291 or
 292 .Dv SEEK_END
 293 to indicate that the relative offset,
 294 .Fa l_start
 295 bytes, will be measured from the start of the file,
 296 current position, or end of the file, respectively.
 297 The value of
 298 .Fa l_len
 299 is the number of consecutive bytes to be locked.
 300 If
 301 .Fa l_len
 302 is negative, the result is undefined.
 303 The
 304 .Fa l_pid
 305 field is only used with
 306 .Dv F_GETLK
 307 to return the process ID of the process holding a blocking lock.
 308 After a successful
 309 .Dv F_GETLK
 310 request, the value of
 311 .Fa l_whence
 312 is
 313 .Dv SEEK_SET .
 314 .Pp
 315 Locks may start and extend beyond the current end of a file,
 316 but may not start or extend before the beginning of the file.
 317 A lock is set to extend to the largest possible value of the
 318 file offset for that file if
 319 .Fa l_len
 320 is set to zero.
 321 If
 322 .Fa l_whence
 323 and
 324 .Fa l_start
 325 point to the beginning of the file, and
 326 .Fa l_len
 327 is zero, the entire file is locked.
 328 If an application wishes only to do entire file locking, the
 329 .Xr flock 2
 330 system call is much more efficient.
 331 .Pp
 332 There is at most one type of lock set for each byte in the file.
 333 Before a successful return from an
 334 .Dv F_SETLK
 335 or an
 336 .Dv F_SETLKW
 337 request when the calling process has previously existing locks
 338 on bytes in the region specified by the request,
 339 the previous lock type for each byte in the specified
 340 region is replaced by the new lock type.
 341 As specified above under the descriptions
 342 of shared locks and exclusive locks, an
 343 .Dv F_SETLK
 344 or an
 345 .Dv F_SETLKW
 346 request fails or blocks respectively when another process has existing
 347 locks on bytes in the specified region and the type of any of those
 348 locks conflicts with the type specified in the request.
 349 .Pp
 350 This interface follows the completely stupid semantics of System V and
 351 .St -p1003.1-88
 352 that require that all locks associated with a file for a given process are
 353 removed when
 354 .Em any
 355 file descriptor for that file is closed by that process.
 356 This semantic means that applications must be aware of any files that
 357 a subroutine library may access.
 358 For example if an application for updating the password file locks the
 359 password file database while making the update, and then calls
 360 .Xr getpwnam 3
 361 to retrieve a record,
 362 the lock will be lost because
 363 .Xr getpwnam 3
 364 opens, reads, and closes the password database.
 365 The database close will release all locks that the process has
 366 associated with the database, even if the library routine never
 367 requested a lock on the database.
 368 Another minor semantic problem with this interface is that
 369 locks are not inherited by a child process created using the
 370 .Xr fork 2
 371 system call.
 372 The
 373 .Xr flock 2
 374 interface has much more rational last close semantics and
 375 allows locks to be inherited by child processes.
 376 The
 377 .Xr flock 2
 378 system call is recommended for applications that want to ensure the integrity
 379 of their locks when using library routines or wish to pass locks
 380 to their children.
 381 .Pp
 382 The
 383 .Fn fcntl ,
 384 .Xr flock 2 ,
 385 and
 386 .Xr lockf 3
 387 locks are compatible.
 388 Processes using different locking interfaces can cooperate
 389 over the same file safely.
 390 However, only one of such interfaces should be used within
 391 the same process.
 392 If a file is locked by a process through
 393 .Xr flock 2 ,
 394 any record within the file will be seen as locked
 395 from the viewpoint of another process using
 396 .Fn fcntl
 397 or
 398 .Xr lockf 3 ,
 399 and vice versa.
 400 Note that
 401 .Fn fcntl F_GETLK
 402 returns \-1 in
 403 .Fa l_pid
 404 if the process holding a blocking lock previously locked the
 405 file descriptor by
 406 .Xr flock 2 .
 407 .Pp
 408 All locks associated with a file for a given process are
 409 removed when the process terminates.
 410 .Pp
 411 All locks obtained before a call to
 412 .Xr execve 2
 413 remain in effect until the new program releases them.
 414 If the new program does not know about the locks, they will not be
 415 released until the program exits.
 416 .Pp
 417 A potential for deadlock occurs if a process controlling a locked region
 418 is put to sleep by attempting to lock the locked region of another process.
 419 This implementation detects that sleeping until a locked region is unlocked
 420 would cause a deadlock and fails with an
 421 .Er EDEADLK
 422 error.
 423 .Sh RETURN VALUES
 424 Upon successful completion, the value returned depends on
 425 .Fa cmd
 426 as follows:
 427 .Bl -tag -width F_GETOWNX -offset indent
 428 .It Dv F_DUPFD
 429 A new file descriptor.
 430 .It Dv F_DUP2FD
 431 A file descriptor equal to
 432 .Fa arg .
 433 .It Dv F_GETFD
 434 Value of flag (only the low-order bit is defined).
 435 .It Dv F_GETFL
 436 Value of flags.
 437 .It Dv F_GETOWN
 438 Value of file descriptor owner.
 439 .It other
 440 Value other than -1.
 441 .El
 442 .Pp
 443 Otherwise, a value of -1 is returned and
 444 .Va errno
 445 is set to indicate the error.
 446 .Sh ERRORS
 447 The
 448 .Fn fcntl
 449 system call will fail if:
 450 .Bl -tag -width Er
 451 .It Bq Er EAGAIN
 452 The argument
 453 .Fa cmd
 454 is
 455 .Dv F_SETLK ,
 456 the type of lock
 457 .Pq Fa l_type
 458 is a shared lock
 459 .Pq Dv F_RDLCK
 460 or exclusive lock
 461 .Pq Dv F_WRLCK ,
 462 and the segment of a file to be locked is already
 463 exclusive-locked by another process;
 464 or the type is an exclusive lock and some portion of the
 465 segment of a file to be locked is already shared-locked or
 466 exclusive-locked by another process.
 467 .It Bq Er EBADF
 468 The
 469 .Fa fd
 470 argument
 471 is not a valid open file descriptor.
 472 .Pp
 473 The argument
 474 .Fa cmd
 475 is
 476 .Dv F_DUP2FD ,
 477 and
 478 .Fa arg
 479 is not a valid file descriptor.
 480 .Pp
 481 The argument
 482 .Fa cmd
 483 is
 484 .Dv F_SETLK
 485 or
 486 .Dv F_SETLKW ,
 487 the type of lock
 488 .Pq Fa l_type
 489 is a shared lock
 490 .Pq Dv F_RDLCK ,
 491 and
 492 .Fa fd
 493 is not a valid file descriptor open for reading.
 494 .Pp
 495 The argument
 496 .Fa cmd
 497 is
 498 .Dv F_SETLK
 499 or
 500 .Dv F_SETLKW ,
 501 the type of lock
 502 .Pq Fa l_type
 503 is an exclusive lock
 504 .Pq Dv F_WRLCK ,
 505 and
 506 .Fa fd
 507 is not a valid file descriptor open for writing.
 508 .It Bq Er EDEADLK
 509 The argument
 510 .Fa cmd
 511 is
 512 .Dv F_SETLKW ,
 513 and a deadlock condition was detected.
 514 .It Bq Er EINTR
 515 The argument
 516 .Fa cmd
 517 is
 518 .Dv F_SETLKW ,
 519 and the system call was interrupted by a signal.
 520 .It Bq Er EINVAL
 521 The
 522 .Fa cmd
 523 argument
 524 is
 525 .Dv F_DUPFD
 526 and
 527 .Fa arg
 528 is negative or greater than the maximum allowable number
 529 (see
 530 .Xr getdtablesize 2 ) .
 531 .Pp
 532 The argument
 533 .Fa cmd
 534 is
 535 .Dv F_GETLK ,
 536 .Dv F_SETLK
 537 or
 538 .Dv F_SETLKW
 539 and the data to which
 540 .Fa arg
 541 points is not valid.
 542 .It Bq Er EMFILE
 543 The argument
 544 .Fa cmd
 545 is
 546 .Dv F_DUPFD
 547 and the maximum number of file descriptors permitted for the
 548 process are already in use,
 549 or no file descriptors greater than or equal to
 550 .Fa arg
 551 are available.
 552 .It Bq Er ENOLCK
 553 The argument
 554 .Fa cmd
 555 is
 556 .Dv F_SETLK
 557 or
 558 .Dv F_SETLKW ,
 559 and satisfying the lock or unlock request would result in the
 560 number of locked regions in the system exceeding a system-imposed limit.
 561 .It Bq Er EPERM
 562 The
 563 .Fa cmd
 564 argument
 565 is
 566 .Dv F_SETOWN
 567 and
 568 the process ID or process group given as an argument is in a
 569 different session than the caller.
 570 .It Bq Er ERANGE
 571 The
 572 .Fa cmd
 573 argument is
 574 .Dv F_GETPATH
 575 and the resulting path, inclusive of the terminator, would be greater than
 576 .Dv MAXPATHLEN .
 577 .It Bq Er ESRCH
 578 The
 579 .Fa cmd
 580 argument
 581 is
 582 .Dv F_SETOWN
 583 and
 584 the process ID given as argument is not in use.
 585 .El
 586 .Pp
 587 In addition, if
 588 .Fa fd
 589 refers to a descriptor open on a terminal device (as opposed to a
 590 descriptor open on a socket), a
 591 .Fa cmd
 592 of
 593 .Dv F_SETOWN
 594 can fail for the same reasons as in
 595 .Xr tcsetpgrp 3 ,
 596 and a
 597 .Fa cmd
 598 of
 599 .Dv F_GETOWN
 600 for the reasons as stated in
 601 .Xr tcgetpgrp 3 .
 602 .Sh SEE ALSO
 603 .Xr close 2 ,
 604 .Xr dup2 2 ,
 605 .Xr execve 2 ,
 606 .Xr flock 2 ,
 607 .Xr getdtablesize 2 ,
 608 .Xr open 2 ,
 609 .Xr sigaction 2 ,
 610 .Xr lockf 3 ,
 611 .Xr tcgetpgrp 3 ,
 612 .Xr tcsetpgrp 3
 613 .Sh STANDARDS
 614 The
 615 .Dv F_DUP2FD
 616 constant is non portable.
 617 It is provided for compatibility with AIX and Solaris.
 618 .Sh HISTORY
 619 The
 620 .Fn fcntl
 621 system call appeared in
 622 .Bx 4.2 .
 623 .Pp
 624 The
 625 .Dv F_DUPFD_CLOEXEC ,
 626 .Dv F_DUP2FD
 627 and
 628 .Dv F_DUP2FD_CLOEXEC
 629 constants first appeared in
 630 .Dx 3.5 .
 631 .Pp
 632 The
 633 .Dv F_GETPATH
 634 constant was introduced in
 635 .Dx 5.9 .