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