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.\" 4. 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 February 8, 2013 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 366This interface follows the completely stupid semantics of System V and 367.St -p1003.1-88 368that require that all locks associated with a file for a given process are 369removed when 370.Em any 371file descriptor for that file is closed by that process. 372This semantic means that applications must be aware of any files that 373a subroutine library may access. 374For example if an application for updating the password file locks the 375password file database while making the update, and then calls 376.Xr getpwnam 3 377to retrieve a record, 378the lock will be lost because 379.Xr getpwnam 3 380opens, reads, and closes the password database. 381The database close will release all locks that the process has 382associated with the database, even if the library routine never 383requested a lock on the database. 384Another minor semantic problem with this interface is that 385locks are not inherited by a child process created using the 386.Xr fork 2 387system call. 388The 389.Xr flock 2 390interface has much more rational last close semantics and 391allows locks to be inherited by child processes. 392The 393.Xr flock 2 394system call is recommended for applications that want to ensure the integrity 395of their locks when using library routines or wish to pass locks 396to their children. 397.Pp 398The 399.Fn fcntl , 400.Xr flock 2 , 401and 402.Xr lockf 3 403locks are compatible. 404Processes using different locking interfaces can cooperate 405over the same file safely. 406However, only one of such interfaces should be used within 407the same process. 408If a file is locked by a process through 409.Xr flock 2 , 410any record within the file will be seen as locked 411from the viewpoint of another process using 412.Fn fcntl 413or 414.Xr lockf 3 , 415and vice versa. 416Note that 417.Fn fcntl F_GETLK 418returns \-1 in 419.Fa l_pid 420if the process holding a blocking lock previously locked the 421file descriptor by 422.Xr flock 2 . 423.Pp 424All locks associated with a file for a given process are 425removed when the process terminates. 426.Pp 427All locks obtained before a call to 428.Xr execve 2 429remain in effect until the new program releases them. 430If the new program does not know about the locks, they will not be 431released until the program exits. 432.Pp 433A potential for deadlock occurs if a process controlling a locked region 434is put to sleep by attempting to lock the locked region of another process. 435This implementation detects that sleeping until a locked region is unlocked 436would cause a deadlock and fails with an 437.Er EDEADLK 438error. 439.Sh RETURN VALUES 440Upon successful completion, the value returned depends on 441.Fa cmd 442as follows: 443.Bl -tag -width F_GETOWNX -offset indent 444.It Dv F_DUPFD 445A new file descriptor. 446.It Dv F_DUP2FD 447A file descriptor equal to 448.Fa arg . 449.It Dv F_GETFD 450Value of flag (only the low-order bit is defined). 451.It Dv F_GETFL 452Value of flags. 453.It Dv F_GETOWN 454Value of file descriptor owner. 455.It other 456Value other than -1. 457.El 458.Pp 459Otherwise, a value of -1 is returned and 460.Va errno 461is set to indicate the error. 462.Sh ERRORS 463The 464.Fn fcntl 465system call will fail if: 466.Bl -tag -width Er 467.It Bq Er EAGAIN 468The argument 469.Fa cmd 470is 471.Dv F_SETLK , 472the type of lock 473.Pq Fa l_type 474is a shared lock 475.Pq Dv F_RDLCK 476or exclusive lock 477.Pq Dv F_WRLCK , 478and the segment of a file to be locked is already 479exclusive-locked by another process; 480or the type is an exclusive lock and some portion of the 481segment of a file to be locked is already shared-locked or 482exclusive-locked by another process. 483.It Bq Er EBADF 484The 485.Fa fd 486argument 487is not a valid open file descriptor. 488.Pp 489The argument 490.Fa cmd 491is 492.Dv F_DUP2FD , 493and 494.Fa arg 495is not a valid file descriptor. 496.Pp 497The argument 498.Fa cmd 499is 500.Dv F_SETLK 501or 502.Dv F_SETLKW , 503the type of lock 504.Pq Fa l_type 505is a shared lock 506.Pq Dv F_RDLCK , 507and 508.Fa fd 509is not a valid file descriptor open for reading. 510.Pp 511The argument 512.Fa cmd 513is 514.Dv F_SETLK 515or 516.Dv F_SETLKW , 517the type of lock 518.Pq Fa l_type 519is an exclusive lock 520.Pq Dv F_WRLCK , 521and 522.Fa fd 523is not a valid file descriptor open for writing. 524.It Bq Er EDEADLK 525The argument 526.Fa cmd 527is 528.Dv F_SETLKW , 529and a deadlock condition was detected. 530.It Bq Er EINTR 531The argument 532.Fa cmd 533is 534.Dv F_SETLKW , 535and the system call was interrupted by a signal. 536.It Bq Er EINVAL 537The 538.Fa cmd 539argument 540is 541.Dv F_DUPFD 542and 543.Fa arg 544is negative or greater than the maximum allowable number 545(see 546.Xr getdtablesize 2 ) . 547.Pp 548The argument 549.Fa cmd 550is 551.Dv F_GETLK , 552.Dv F_SETLK 553or 554.Dv F_SETLKW 555and the data to which 556.Fa arg 557points is not valid. 558.It Bq Er EMFILE 559The argument 560.Fa cmd 561is 562.Dv F_DUPFD 563and the maximum number of file descriptors permitted for the 564process are already in use, 565or no file descriptors greater than or equal to 566.Fa arg 567are available. 568.It Bq Er ENOLCK 569The argument 570.Fa cmd 571is 572.Dv F_SETLK 573or 574.Dv F_SETLKW , 575and satisfying the lock or unlock request would result in the 576number of locked regions in the system exceeding a system-imposed limit. 577.It Bq Er EOPNOTSUPP 578The argument 579.Fa cmd 580is 581.Dv F_GETLK , 582.Dv F_SETLK 583or 584.Dv F_SETLKW 585and 586.Fa fd 587refers to a file for which locking is not supported. 588.It Bq Er EOVERFLOW 589The argument 590.Fa cmd 591is 592.Dv F_GETLK , 593.Dv F_SETLK 594or 595.Dv F_SETLKW 596and an 597.Fa off_t 598calculation overflowed. 599.It Bq Er EPERM 600The 601.Fa cmd 602argument 603is 604.Dv F_SETOWN 605and 606the process ID or process group given as an argument is in a 607different session than the caller. 608.It Bq Er ESRCH 609The 610.Fa cmd 611argument 612is 613.Dv F_SETOWN 614and 615the process ID given as argument is not in use. 616.El 617.Pp 618In addition, if 619.Fa fd 620refers to a descriptor open on a terminal device (as opposed to a 621descriptor open on a socket), a 622.Fa cmd 623of 624.Dv F_SETOWN 625can fail for the same reasons as in 626.Xr tcsetpgrp 3 , 627and a 628.Fa cmd 629of 630.Dv F_GETOWN 631for the reasons as stated in 632.Xr tcgetpgrp 3 . 633.Sh SEE ALSO 634.Xr close 2 , 635.Xr dup2 2 , 636.Xr execve 2 , 637.Xr flock 2 , 638.Xr getdtablesize 2 , 639.Xr open 2 , 640.Xr sigaction 2 , 641.Xr lockf 3 , 642.Xr tcgetpgrp 3 , 643.Xr tcsetpgrp 3 644.Sh STANDARDS 645The 646.Dv F_DUP2FD 647constant is non portable. 648It is provided for compatibility with AIX and Solaris. 649.Sh HISTORY 650The 651.Fn fcntl 652system call appeared in 653.Bx 4.2 . 654.Pp 655The 656.Dv F_DUP2FD 657constant first appeared in 658.Fx 7.1 . 659