1.\" $NetBSD: fcntl.2,v 1.45 2019/09/27 07:20:07 wiz 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 September 26, 2019 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.Ar 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.Fa MAXPATHLEN . 165.El 166.Pp 167The set of valid flags for the 168.Dv F_GETFL 169and 170.Dv F_SETFL 171flags are as follows: 172.Dv O_APPEND , 173.Dv O_ASYNC , 174.Dv O_SYNC , 175.Dv O_NONBLOCK , 176.Dv O_DSYNC , 177.Dv O_RSYNC , 178.Dv O_ALT_IO , 179.Dv O_DIRECT , 180.Dv O_NOSIGPIPE . 181These flags are described in 182.Xr open 2 . 183.Pp 184Several commands are available for doing advisory file locking; 185they all operate on the following structure: 186.Bd -literal 187struct flock { 188 off_t l_start; /* starting offset */ 189 off_t l_len; /* len = 0 means until end of file */ 190 pid_t l_pid; /* lock owner */ 191 short l_type; /* lock type: read/write, etc. */ 192 short l_whence; /* type of l_start */ 193}; 194.Ed 195.Pp 196The commands available for advisory record locking are as follows: 197.Bl -tag -width F_SETLKWX 198.It Dv F_GETLK 199Get the first lock that blocks the lock description pointed to by the 200third argument, 201.Fa arg , 202taken as a pointer to a 203.Fa "struct flock" 204(see above). 205The information retrieved overwrites the information passed to 206.Nm 207in the 208.Fa flock 209structure. 210If no lock is found that would prevent this lock from being created, 211the structure is left unchanged by this function call except for the 212lock type 213.Fa l_type , 214which is set to 215.Dv F_UNLCK . 216.It Dv F_SETLK 217Set or clear a file segment lock according to the lock description 218pointed to by the third argument, 219.Fa arg , 220taken as a pointer to a 221.Fa "struct flock" 222(see above). 223As specified by the value of 224.Fa l_type , 225.Dv F_SETLK 226is used to establish shared (or read) locks 227.Pq Dv F_RDLCK 228or exclusive (or write) locks, 229.Pq Dv F_WRLCK , 230as well as remove either type of lock 231.Pq Dv F_UNLCK . 232If a shared or exclusive lock cannot be set, 233.Nm 234returns immediately with 235.Er EAGAIN . 236.It Dv F_SETLKW 237This command is the same as 238.Dv F_SETLK 239except that if a shared or exclusive lock is blocked by other locks, 240the process waits until the request can be satisfied. 241If a signal that is to be caught is received while 242.Nm 243is waiting for a region, the 244.Nm 245will be interrupted if the signal handler has not specified the 246.Dv SA_RESTART 247(see 248.Xr sigaction 2 ) . 249.El 250.Pp 251When a shared lock has been set on a segment of a file, 252other processes can set shared locks on that segment 253or a portion of it. 254A shared lock prevents any other process from setting an exclusive 255lock on any portion of the protected area. 256A request for a shared lock fails if the file descriptor was not 257opened with read access. 258.Pp 259An exclusive lock prevents any other process from setting a shared lock or 260an exclusive lock on any portion of the protected area. 261A request for an exclusive lock fails if the file was not 262opened with write access. 263.Pp 264The value of 265.Fa l_whence 266is 267.Dv SEEK_SET , 268.Dv SEEK_CUR , 269or 270.Dv SEEK_END 271to indicate that the relative offset, 272.Fa l_start 273bytes, will be measured from the start of the file, 274current position, or end of the file, respectively. 275The value of 276.Fa l_len 277is the number of consecutive bytes to be locked. 278If 279.Fa l_len 280is negative, the result is undefined. 281The 282.Fa l_pid 283field is only used with 284.Dv F_GETLK 285to return the process ID of the process holding a blocking lock. 286After a successful 287.Dv F_GETLK 288request, the value of 289.Fa l_whence 290is 291.Dv SEEK_SET . 292.Pp 293Locks may start and extend beyond the current end of a file, 294but may not start or extend before the beginning of the file. 295A lock is set to extend to the largest possible value of the 296file offset for that file if 297.Fa l_len 298is set to zero. 299If 300.Fa l_whence 301and 302.Fa l_start 303point to the beginning of the file, and 304.Fa l_len 305is zero, the entire file is locked. 306If an application wishes only to do entire file locking, the 307.Xr flock 2 308system call is much more efficient. 309.Pp 310There is at most one type of lock set for each byte in the file. 311Before a successful return from an 312.Dv F_SETLK 313or an 314.Dv F_SETLKW 315request when the calling process has previously existing locks 316on bytes in the region specified by the request, 317the previous lock type for each byte in the specified 318region is replaced by the new lock type. 319As specified above under the descriptions 320of shared locks and exclusive locks, an 321.Dv F_SETLK 322or an 323.Dv F_SETLKW 324request fails or blocks respectively when another process has existing 325locks on bytes in the specified region and the type of any of those 326locks conflicts with the type specified in the request. 327.Sh NOTES 328The 329.Dv F_GETPATH 330functionality is implemented using the reverse 331.Xr namei 9 332cache. 333The implications of this are: 334.Bl -bullet -compact 335.It 336For hard links where the file descriptor can resolve to multiple pathnames, 337the first entry found in the cache is returned. 338.It 339.Dv F_GETPATH 340may fail if the corresponding entry has been evicted from the LRU 341.Xr namei 9 342cache and return 343.Dv ENOENT . 344.It 345File descriptors that don't point to vnodes are not handled, as 346well as symbolic links since there is currently no way to obtain 347a file descriptor pointing to a symbolic link. 348.El 349.Sh RETURN VALUES 350Upon successful completion, the value returned depends on 351.Fa cmd 352as follows: 353.Bl -tag -width F_GETOWNX -offset indent 354.It Dv F_DUPFD 355A new file descriptor. 356.It Dv F_GETFD 357Value of flag (only the low-order bit is defined). 358.It Dv F_GETFL 359Value of flags. 360.It Dv F_GETOWN 361Value of file descriptor owner. 362.It Dv F_MAXFD 363Value of the highest file descriptor open by the process. 364.It other 365Value other than \-1. 366.El 367.Pp 368Otherwise, a value of \-1 is returned and 369.Va errno 370is set to indicate the error. 371.Sh COMPATIBILITY 372This interface follows the completely stupid semantics of 373.At V 374and 375.St -p1003.1-88 376that require that all locks associated with a file for a given process are 377removed when \fIany\fP file descriptor for that file is closed by that process. 378This semantic means that applications must be aware of any files that 379a subroutine library may access. 380For example if an application for updating the password file locks the 381password file database while making the update, and then calls 382.Xr getpwnam 3 383to retrieve a record, 384the lock will be lost because 385.Xr getpwnam 3 386opens, reads, and closes the password database. 387The database close will release all locks that the process has 388associated with the database, even if the library routine never 389requested a lock on the database. 390.Pp 391Another minor semantic problem with this interface is that 392locks are not inherited by a child process created using the 393.Xr fork 2 394function. 395The 396.Xr flock 2 397interface has much more rational last close semantics and 398allows locks to be inherited by child processes. 399Calling 400.Xr flock 2 401is recommended for applications that want to ensure the integrity 402of their locks when using library routines or wish to pass locks 403to their children. 404Note that 405.Xr flock 2 406and 407.Nm 408locks may be safely used concurrently. 409.Pp 410All locks associated with a file for a given process are 411removed when the process terminates. 412.Pp 413A potential for deadlock occurs if a process controlling a locked region 414is put to sleep by attempting to lock the locked region of another process. 415This implementation detects that sleeping until a locked region is unlocked 416would cause a deadlock and fails with an 417.Er EDEADLK 418error. 419.Sh ERRORS 420.Fn fcntl 421will fail if: 422.Bl -tag -width Er 423.It Bq Er EACCES 424The argument 425.Fa cmd 426is 427.Dv F_GETPATH 428and read or search permission was denied for a component of the pathname. 429.It Bq Er EAGAIN 430The argument 431.Fa arg 432is 433.Dv F_SETLK , 434the type of lock 435.Pq Fa l_type 436is a shared lock 437.Pq Dv F_RDLCK 438or exclusive lock 439.Pq Dv F_WRLCK , 440and the segment of a file to be locked is already 441exclusive-locked by another process; 442or the type is an exclusive lock and some portion of the 443segment of a file to be locked is already shared-locked or 444exclusive-locked by another process. 445.It Bq Er EBADF 446.Fa fildes 447is not a valid open file descriptor. 448.Pp 449The argument 450.Fa cmd 451is 452.Dv F_SETLK 453or 454.Dv F_SETLKW , 455the type of lock 456.Pq Fa l_type 457is a shared lock 458.Pq Dv F_RDLCK , 459and 460.Fa fildes 461is not a valid file descriptor open for reading. 462.Pp 463The argument 464.Fa cmd 465is 466.Dv F_SETLK 467or 468.Dv F_SETLKW , 469the type of lock 470.Pq Fa l_type 471is an exclusive lock 472.Pq Dv F_WRLCK , 473and 474.Fa fildes 475is not a valid file descriptor open for writing. 476.It Bq Er EDEADLK 477The argument 478.Fa cmd 479is 480.Dv F_SETLKW , 481and a deadlock condition was detected. 482.It Bq Er EINTR 483The argument 484.Fa cmd 485is 486.Dv F_SETLKW , 487and the function was interrupted by a signal. 488.It Bq Er EINVAL 489The argument 490.Fa cmd 491is invalid. 492.Pp 493The argument 494.Fa cmd 495is 496.Dv F_DUPFD 497and 498.Fa arg 499is negative or greater than the maximum allowable number 500(see 501.Xr getdtablesize 3 ) . 502.Pp 503The argument 504.Fa cmd 505is 506.Dv F_GETLK , 507.Dv F_SETLK , 508or 509.Dv F_SETLKW 510and the data to which 511.Fa arg 512points is not valid, or 513.Fa fildes 514refers to a file that does not support locking. 515.It Bq Er EMFILE 516The argument 517.Fa cmd 518is 519.Dv F_DUPFD 520and the maximum number of file descriptors permitted for the 521process are already in use, 522or no file descriptors greater than or equal to 523.Fa arg 524are available. 525.It Bq Er ENFILE 526.Fa cmd 527is 528.Dv F_DUPFD 529and system-wide the maximum allowed number of file descriptors are 530currently open. 531.It Bq Er ENOENT 532The argument 533.Fa cmd 534is 535.Dv F_GETPATH 536and a component of the pathname no longer exists. 537.It Bq Er ENOLCK 538The argument 539.Fa cmd 540is 541.Dv F_SETLK 542or 543.Dv F_SETLKW , 544and satisfying the lock or unlock request would result in the 545number of locked regions in the system exceeding a system-imposed limit. 546.It Bq Er ENOMEM 547The argument 548.Fa cmd 549is 550.Dv F_GETPATH 551and insufficient memory is available. 552.It Bq Er ERANGE 553The argument 554.Fa cmd 555is 556.Dv F_GETPATH 557and the resulting path would be greater than 558.Dv MAXPATHLEN . 559.It Bq Er ESRCH 560.Fa cmd 561is 562.Dv F_SETOWN 563and 564the process ID given as argument is not in use. 565.El 566.Sh SEE ALSO 567.Xr close 2 , 568.Xr execve 2 , 569.Xr flock 2 , 570.Xr open 2 , 571.Xr sigaction 2 , 572.Xr getdtablesize 3 573.Sh STANDARDS 574The 575.Fn fcntl 576function conforms to 577.St -p1003.1-90 . 578.Sh HISTORY 579The 580.Fn fcntl 581function call appeared in 582.Bx 4.2 . 583