1.\" $NetBSD: fcntl.2,v 1.50 2023/07/10 02:31:54 christos Exp $ 2.\" 3.\" Copyright (c) 1983, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94 31.\" 32.Dd July 5, 2023 33.Dt FCNTL 2 34.Os 35.Sh NAME 36.Nm fcntl 37.Nd file descriptor control 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In fcntl.h 42.Ft int 43.Fn fcntl "int fd" "int cmd" "..." 44.Sh DESCRIPTION 45.Fn fcntl 46provides for control over descriptors. 47The argument 48.Fa fd 49is a descriptor to be operated on by 50.Fa cmd 51as described below. 52The third parameter is called 53.Fa arg 54and is technically a pointer to void, but it is 55interpreted as an int by some commands and ignored by others. 56.Pp 57Commands are: 58.Bl -tag -width F_DUPFD_CLOEXEC 59.It Dv F_DUPFD 60Return a new descriptor as follows: 61.Pp 62.Bl -bullet -compact -offset 4n 63.It 64Lowest numbered available descriptor greater than or equal to 65.Fa arg , 66which is interpreted as an int. 67.It 68Same object references as the original descriptor. 69.It 70New descriptor shares the same file offset if the object 71was a file. 72.It 73Same access mode (read, write or read/write). 74.It 75Same file status flags (i.e., both file descriptors 76share the same file status flags). 77.It 78The close-on-exec flag associated with the new file descriptor 79is cleared to remain open across 80.Xr execve 2 81system calls. 82.El 83.It Dv F_DUPFD_CLOEXEC 84Same as 85.Dv F_DUPFD , 86but sets the close-on-exec property on the file descriptor created. 87.It Dv F_GETFD 88Get the close-on-exec flag associated with the file descriptor 89.Fa fd 90as 91.Dv FD_CLOEXEC . 92If the returned value ANDed with 93.Dv FD_CLOEXEC 94is 0, 95the file will remain open across 96.Fn exec , 97otherwise the file will be closed upon execution of 98.Fn exec 99.Fa ( arg 100is ignored). 101.It Dv F_SETFD 102Set the close-on-exec flag associated with 103.Fa fd 104to 105.Fa arg , 106where 107.Fa arg 108is either 0 or 109.Dv FD_CLOEXEC , 110as described above. 111.It Dv F_GETFL 112Get descriptor status flags, as described below 113.Fa ( arg 114is ignored). 115.It Dv F_SETFL 116Set descriptor status flags to 117.Fa arg , 118which is interpreted as an int. 119.It Dv F_GETOWN 120Get the process ID or process group 121currently receiving 122.Dv SIGIO 123and 124.Dv SIGURG 125signals; process groups are returned 126as negative values 127.Fa ( arg 128is ignored). 129.It Dv F_SETOWN 130Set the process or process group 131to receive 132.Dv SIGIO 133and 134.Dv SIGURG 135signals; 136process groups are specified by supplying 137.Fa arg 138as negative, otherwise 139.Fa arg 140is interpreted as a process ID. 141The argument 142.Fa arg 143is interpreted as an int. 144.It Dv F_CLOSEM 145Close all file descriptors greater than or equal to 146.Fa fd . 147.It Dv F_MAXFD 148Return the maximum file descriptor number currently open by the process. 149.It Dv F_GETNOSIGPIPE 150Return if the 151.Dv O_NOSIGPIPE 152flag is set in the file descriptor. 153.It Dv F_SETNOSIGPIPE 154Set or clear the 155.Dv O_NOSIGPIPE 156in the file descriptor. 157.It Dv F_GETPATH 158Place a pathname corresponding to 159.Fa fd 160in the buffer pointed to by 161.Fa arg . 162.Fa arg 163should be pointing to a buffer of at least 164.Dv MAXPATHLEN . 165.It Dv F_ADD_SEALS 166Add seals specified in 167.Fa arg 168to 169.Fa fd 170to restrict possible operations on 171.Fa fd 172as described below. 173Like flags, multiple seals can be specified at once. 174Additionally, specifying seals that are already associated with 175.Fa fd 176is a no-op. 177.It Dv F_GET_SEALS 178Get the seals currently associated with 179.Fa fd 180as described below 181.Fa ( arg 182is ignored). 183.El 184.Pp 185The set of valid flags for the 186.Dv F_GETFL 187and 188.Dv F_SETFL 189flags are as follows: 190.Dv O_APPEND , 191.Dv O_ASYNC , 192.Dv O_SYNC , 193.Dv O_NONBLOCK , 194.Dv O_DSYNC , 195.Dv O_RSYNC , 196.Dv O_ALT_IO , 197.Dv O_DIRECT , 198.Dv O_NOSIGPIPE . 199These flags are described in 200.Xr open 2 . 201.Pp 202Several commands are available for doing advisory file locking; 203they all operate on the following structure: 204.Bd -literal 205struct flock { 206 off_t l_start; /* starting offset */ 207 off_t l_len; /* len = 0 means until end of file */ 208 pid_t l_pid; /* lock owner */ 209 short l_type; /* lock type: read/write, etc. */ 210 short l_whence; /* type of l_start */ 211}; 212.Ed 213.Pp 214The commands available for advisory record locking are as follows: 215.Bl -tag -width F_SETLKWX 216.It Dv F_GETLK 217Get the first lock that blocks the lock description pointed to by the 218third argument, 219.Fa arg , 220taken as a pointer to a 221.Fa "struct flock" 222(see above). 223The information retrieved overwrites the information passed to 224.Nm 225in the 226.Fa flock 227structure. 228If no lock is found that would prevent this lock from being created, 229the structure is left unchanged by this function call except for the 230lock type 231.Fa l_type , 232which is set to 233.Dv F_UNLCK . 234.It Dv F_SETLK 235Set or clear a file segment lock according to the lock description 236pointed to by the third argument, 237.Fa arg , 238taken as a pointer to a 239.Fa "struct flock" 240(see above). 241As specified by the value of 242.Fa l_type , 243.Dv F_SETLK 244is used to establish shared (or read) locks 245.Pq Dv F_RDLCK 246or exclusive (or write) locks, 247.Pq Dv F_WRLCK , 248as well as remove either type of lock 249.Pq Dv F_UNLCK . 250If a shared or exclusive lock cannot be set, 251.Nm 252returns immediately with 253.Er EAGAIN . 254.It Dv F_SETLKW 255This command is the same as 256.Dv F_SETLK 257except that if a shared or exclusive lock is blocked by other locks, 258the process waits until the request can be satisfied. 259If a signal that is to be caught is received while 260.Nm 261is waiting for a region, the 262.Nm 263will be interrupted if the signal handler has not specified the 264.Dv SA_RESTART 265(see 266.Xr sigaction 2 ) . 267.El 268.Pp 269When a shared lock has been set on a segment of a file, 270other processes can set shared locks on that segment 271or a portion of it. 272A shared lock prevents any other process from setting an exclusive 273lock on any portion of the protected area. 274A request for a shared lock fails if the file descriptor was not 275opened with read access. 276.Pp 277An exclusive lock prevents any other process from setting a shared lock or 278an exclusive lock on any portion of the protected area. 279A request for an exclusive lock fails if the file was not 280opened with write access. 281.Pp 282The value of 283.Fa l_whence 284is 285.Dv SEEK_SET , 286.Dv SEEK_CUR , 287or 288.Dv SEEK_END 289to indicate that the relative offset, 290.Fa l_start 291bytes, will be measured from the start of the file, 292current position, or end of the file, respectively. 293The value of 294.Fa l_len 295is the number of consecutive bytes to be locked. 296If 297.Fa l_len 298is negative, the result is undefined. 299The 300.Fa l_pid 301field is only used with 302.Dv F_GETLK 303to return the process ID of the process holding a blocking lock. 304After a successful 305.Dv F_GETLK 306request, the value of 307.Fa l_whence 308is 309.Dv SEEK_SET . 310.Pp 311Locks may start and extend beyond the current end of a file, 312but may not start or extend before the beginning of the file. 313A lock is set to extend to the largest possible value of the 314file offset for that file if 315.Fa l_len 316is set to zero. 317If 318.Fa l_whence 319and 320.Fa l_start 321point to the beginning of the file, and 322.Fa l_len 323is zero, the entire file is locked. 324If an application wishes only to do entire file locking, the 325.Xr flock 2 326system call is much more efficient. 327.Pp 328There is at most one type of lock set for each byte in the file. 329Before a successful return from an 330.Dv F_SETLK 331or an 332.Dv F_SETLKW 333request when the calling process has previously existing locks 334on bytes in the region specified by the request, 335the previous lock type for each byte in the specified 336region is replaced by the new lock type. 337As specified above under the descriptions 338of shared locks and exclusive locks, an 339.Dv F_SETLK 340or an 341.Dv F_SETLKW 342request fails or blocks respectively when another process has existing 343locks on bytes in the specified region and the type of any of those 344locks conflicts with the type specified in the request. 345.Pp 346Possible seals are: 347.Bl -tag -width F_SEAL_FUTURE_WRITE 348.It Dv F_SEAL_SEAL 349Prevent any further seals from being added to 350.Fa fd . 351.It Dv F_SEAL_SHRINK 352Prevent the size of 353.Fa fd 354from decreasing. 355.It Dv F_SEAL_GROW 356Prevent the size of 357.Fa fd 358from increasing. 359.It Dv F_SEAL_WRITE 360Prevent any write operations to 361.Fa fd . 362.Dv F_SEAL_WRITE 363cannot be applied if 364.Fa fd 365has any memory mappings. 366.It Dv F_SEAL_FUTURE_WRITE 367Like 368.Dv F_SEAL_WRITE 369but allow any current memory mappings of 370.Fa fd 371to remain open, including those with 372.Dv PROT_WRITE . 373.El 374.Sh NOTES 375For 376.Dv F_GETPATH : 377.Bl -bullet -compact 378.It 379For vnodes, functionality is implemented using the reverse 380.Xr namei 9 381cache. 382The implications of this are 383.Bl -bullet -compact 384.It 385For hard links where the file descriptor can resolve to multiple pathnames, 386the first entry found in the cache is returned. 387.It 388.Dv F_GETPATH 389may fail if the corresponding entry has been evicted from the LRU 390.Xr namei 9 391cache and return 392.Er ENOENT . 393.El 394.It 395For a file descriptor created by 396.Xr memfd_create 2 , 397the name provided at 398.Fa fd 399creation, with the prefix 400.Dq memfd: 401is used. 402.It 403Other types of file descriptors are not handled, as well as symbolic 404links since there is currently no way to obtain a file descriptor 405pointing to a symbolic link. 406.El 407.Sh RETURN VALUES 408Upon successful completion, the value returned depends on 409.Fa cmd 410as follows: 411.Bl -tag -width F_GET_SEALS -offset indent 412.It Dv F_DUPFD 413A new file descriptor. 414.It Dv F_GETFD 415Value of flag (only the low-order bit is defined). 416.It Dv F_GETFL 417Value of flags. 418.It Dv F_GETOWN 419Value of file descriptor owner. 420.It Dv F_MAXFD 421Value of the highest file descriptor open by the process. 422.It Dv F_GET_SEALS 423Value of the seals currently associated with 424.Fa fd . 425.It other 426Value other than \-1. 427.El 428.Pp 429Otherwise, a value of \-1 is returned and 430.Va errno 431is set to indicate the error. 432.Sh COMPATIBILITY 433This interface follows the completely stupid semantics of 434.At V 435and 436.St -p1003.1-88 437that require that all locks associated with a file for a given process are 438removed when \fIany\fP file descriptor for that file is closed by that process. 439This semantic means that applications must be aware of any files that 440a subroutine library may access. 441For example if an application for updating the password file locks the 442password file database while making the update, and then calls 443.Xr getpwnam 3 444to retrieve a record, 445the lock will be lost because 446.Xr getpwnam 3 447opens, reads, and closes the password database. 448The database close will release all locks that the process has 449associated with the database, even if the library routine never 450requested a lock on the database. 451.Pp 452Another minor semantic problem with this interface is that 453locks are not inherited by a child process created using the 454.Xr fork 2 455function. 456The 457.Xr flock 2 458interface has much more rational last close semantics and 459allows locks to be inherited by child processes. 460Calling 461.Xr flock 2 462is recommended for applications that want to ensure the integrity 463of their locks when using library routines or wish to pass locks 464to their children. 465Note that 466.Xr flock 2 467and 468.Nm 469locks may be safely used concurrently. 470.Pp 471All locks associated with a file for a given process are 472removed when the process terminates. 473.Pp 474A potential for deadlock occurs if a process controlling a locked region 475is put to sleep by attempting to lock the locked region of another process. 476This implementation detects that sleeping until a locked region is unlocked 477would cause a deadlock and fails with an 478.Er EDEADLK 479error. 480.Sh ERRORS 481.Fn fcntl 482will fail if: 483.Bl -tag -width Er 484.It Bq Er EACCES 485The argument 486.Fa cmd 487is 488.Dv F_GETPATH 489and read or search permission was denied for a component of the pathname. 490.It Bq Er EAGAIN 491The argument 492.Fa arg 493is 494.Dv F_SETLK , 495the type of lock 496.Pq Fa l_type 497is a shared lock 498.Pq Dv F_RDLCK 499or exclusive lock 500.Pq Dv F_WRLCK , 501and the segment of a file to be locked is already 502exclusive-locked by another process; 503or the type is an exclusive lock and some portion of the 504segment of a file to be locked is already shared-locked or 505exclusive-locked by another process. 506.It Bq Er EBADF 507.Fa fildes 508is not a valid open file descriptor. 509.Pp 510The argument 511.Fa cmd 512is 513.Dv F_SETLK 514or 515.Dv F_SETLKW , 516the type of lock 517.Pq Fa l_type 518is a shared lock 519.Pq Dv F_RDLCK , 520and 521.Fa fildes 522is not a valid file descriptor open for reading. 523.Pp 524The argument 525.Fa cmd 526is 527.Dv F_SETLK 528or 529.Dv F_SETLKW , 530the type of lock 531.Pq Fa l_type 532is an exclusive lock 533.Pq Dv F_WRLCK , 534and 535.Fa fildes 536is not a valid file descriptor open for writing. 537.It Bq Er EBUSY 538The argument 539.Fa cmd 540is 541.Dv F_ADD_SEALS , 542.Fa arg 543contains 544.Dv F_SEAL_WRITE 545and 546.Fa fd 547is currently mapped by 548.Xr mmap 2 . 549.It Bq Er EDEADLK 550The argument 551.Fa cmd 552is 553.Dv F_SETLKW , 554and a deadlock condition was detected. 555.It Bq Er EINTR 556The argument 557.Fa cmd 558is 559.Dv F_SETLKW , 560and the function was interrupted by a signal. 561.It Bq Er EINVAL 562The argument 563.Fa cmd 564is invalid. 565.Pp 566The argument 567.Fa cmd 568is 569.Dv F_DUPFD 570and 571.Fa arg 572is negative or greater than the maximum allowable number 573(see 574.Xr getdtablesize 3 ) . 575.Pp 576The argument 577.Fa cmd 578is 579.Dv F_GETLK , 580.Dv F_SETLK , 581or 582.Dv F_SETLKW 583and the data to which 584.Fa arg 585points is not valid, or 586.Fa fildes 587refers to a file that does not support locking. 588.Pp 589The argument 590.Fa cmd 591is 592.Dv F_ADD_SEALS 593or 594.Dv F_GET_SEALS 595and 596.Fa fd 597does not support seals. 598.Pp 599The argument 600.Fa cmd 601is 602.Dv F_ADD_SEALS 603and 604.Fa arg 605contains set bits for unsupported seals. 606.It Bq Er EMFILE 607The argument 608.Fa cmd 609is 610.Dv F_DUPFD 611and the maximum number of file descriptors permitted for the 612process are already in use, 613or no file descriptors greater than or equal to 614.Fa arg 615are available. 616.It Bq Er ENFILE 617.Fa cmd 618is 619.Dv F_DUPFD 620and system-wide the maximum allowed number of file descriptors are 621currently open. 622.It Bq Er ENOENT 623The argument 624.Fa cmd 625is 626.Dv F_GETPATH 627and a component of the pathname no longer exists. 628.It Bq Er ENOLCK 629The argument 630.Fa cmd 631is 632.Dv F_SETLK 633or 634.Dv F_SETLKW , 635and satisfying the lock or unlock request would result in the 636number of locked regions in the system exceeding a system-imposed limit. 637.It Bq Er ENOMEM 638The argument 639.Fa cmd 640is 641.Dv F_GETPATH 642and insufficient memory is available. 643.Pp 644The argument 645.Fa cmd 646is 647.Dv F_GETLK , 648.Dv F_SETLK , 649or 650.Dv F_SETLKW , 651and the file lock limit for the current unprivileged user 652has been reached. 653It can be modified using the 654.Li kern.maxfiles 655.Xr sysctl 7 . 656.It Bq Er EPERM 657The argument 658.Fa cmd 659is 660.Dv F_ADD_SEALS 661and 662.Fa fd 663already has 664.Dv F_SEAL_SEAL . 665.It Bq Er ERANGE 666The argument 667.Fa cmd 668is 669.Dv F_GETPATH 670and the resulting path would be greater than 671.Dv MAXPATHLEN . 672.It Bq Er ESRCH 673.Fa cmd 674is 675.Dv F_SETOWN 676and 677the process ID given as argument is not in use. 678.El 679.Sh SEE ALSO 680.Xr close 2 , 681.Xr execve 2 , 682.Xr flock 2 , 683.Xr open 2 , 684.Xr sigaction 2 , 685.Xr getdtablesize 3 686.Sh STANDARDS 687The 688.Fn fcntl 689function conforms to 690.St -p1003.1-90 . 691.Sh HISTORY 692The 693.Fn fcntl 694function call appeared in 695.Bx 4.2 . 696