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