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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94 33.\" $FreeBSD$ 34.\" 35.Dd January 12, 1994 36.Dt FCNTL 2 37.Os 38.Sh NAME 39.Nm fcntl 40.Nd file control 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In fcntl.h 45.Ft int 46.Fn fcntl "int fd" "int cmd" "..." 47.Sh DESCRIPTION 48The 49.Fn fcntl 50system call provides for control over descriptors. 51The argument 52.Fa fd 53is a descriptor to be operated on by 54.Fa cmd 55as described below. 56Depending on the value of 57.Fa cmd , 58.Fn fcntl 59can take an additional third argument 60.Fa "int arg" . 61.Bl -tag -width F_GETOWNX 62.It Dv F_DUPFD 63Return a new descriptor as follows: 64.Pp 65.Bl -bullet -compact -offset 4n 66.It 67Lowest numbered available descriptor greater than or equal to 68.Fa arg . 69.It 70Same object references as the original descriptor. 71.It 72New descriptor shares the same file offset if the object 73was a file. 74.It 75Same access mode (read, write or read/write). 76.It 77Same file status flags (i.e., both file descriptors 78share the same file status flags). 79.It 80The close-on-exec flag associated with the new file descriptor 81is set to remain open across 82.Xr execve 2 83system calls. 84.El 85.It Dv F_GETFD 86Get the close-on-exec flag associated with the file descriptor 87.Fa fd 88as 89.Dv FD_CLOEXEC . 90If the returned value ANDed with 91.Dv FD_CLOEXEC 92is 0, 93the file will remain open across 94.Fn exec , 95otherwise the file will be closed upon execution of 96.Fn exec 97.Fa ( arg 98is ignored). 99.It Dv F_SETFD 100Set the close-on-exec flag associated with 101.Fa fd 102to 103.Fa arg , 104where 105.Fa arg 106is either 0 or 107.Dv FD_CLOEXEC , 108as described above. 109.It Dv F_GETFL 110Get descriptor status flags, as described below 111.Fa ( arg 112is ignored). 113.It Dv F_SETFL 114Set descriptor status flags to 115.Fa arg . 116.It Dv F_GETOWN 117Get the process ID or process group 118currently receiving 119.Dv SIGIO 120and 121.Dv SIGURG 122signals; process groups are returned 123as negative values 124.Fa ( arg 125is ignored). 126.It Dv F_SETOWN 127Set the process or process group 128to receive 129.Dv SIGIO 130and 131.Dv SIGURG 132signals; 133process groups are specified by supplying 134.Fa arg 135as negative, otherwise 136.Fa arg 137is interpreted as a process ID. 138.El 139.Pp 140The flags for the 141.Dv F_GETFL 142and 143.Dv F_SETFL 144flags are as follows: 145.Bl -tag -width O_NONBLOCKX 146.It Dv O_NONBLOCK 147Non-blocking I/O; if no data is available to a 148.Xr read 2 149system call, or if a 150.Xr write 2 151operation would block, 152the read or write call returns -1 with the error 153.Er EAGAIN . 154.It Dv O_APPEND 155Force each write to append at the end of file; 156corresponds to the 157.Dv O_APPEND 158flag of 159.Xr open 2 . 160.It Dv O_DIRECT 161Minimize or eliminate the cache effects of reading and writing. 162The system 163will attempt to avoid caching the data you read or write. 164If it cannot 165avoid caching the data, it will minimize the impact the data has on the cache. 166Use of this flag can drastically reduce performance if not used with care. 167.It Dv O_ASYNC 168Enable the 169.Dv SIGIO 170signal to be sent to the process group 171when I/O is possible, e.g., 172upon availability of data to be read. 173.El 174.Pp 175Several commands are available for doing advisory file locking; 176they all operate on the following structure: 177.Bd -literal 178struct flock { 179 off_t l_start; /* starting offset */ 180 off_t l_len; /* len = 0 means until end of file */ 181 pid_t l_pid; /* lock owner */ 182 short l_type; /* lock type: read/write, etc. */ 183 short l_whence; /* type of l_start */ 184}; 185.Ed 186The commands available for advisory record locking are as follows: 187.Bl -tag -width F_SETLKWX 188.It Dv F_GETLK 189Get the first lock that blocks the lock description pointed to by the 190third argument, 191.Fa arg , 192taken as a pointer to a 193.Fa "struct flock" 194(see above). 195The information retrieved overwrites the information passed to 196.Fn fcntl 197in the 198.Fa flock 199structure. 200If no lock is found that would prevent this lock from being created, 201the structure is left unchanged by this system call except for the 202lock type which is set to 203.Dv F_UNLCK . 204.It Dv F_SETLK 205Set or clear a file segment lock according to the lock description 206pointed to by the third argument, 207.Fa arg , 208taken as a pointer to a 209.Fa "struct flock" 210(see above). 211.Dv F_SETLK 212is used to establish shared (or read) locks 213.Pq Dv F_RDLCK 214or exclusive (or write) locks, 215.Pq Dv F_WRLCK , 216as well as remove either type of lock 217.Pq Dv F_UNLCK . 218If a shared or exclusive lock cannot be set, 219.Fn fcntl 220returns immediately with 221.Er EAGAIN . 222.It Dv F_SETLKW 223This command is the same as 224.Dv F_SETLK 225except that if a shared or exclusive lock is blocked by other locks, 226the process waits until the request can be satisfied. 227If a signal that is to be caught is received while 228.Fn fcntl 229is waiting for a region, the 230.Fn fcntl 231will be interrupted if the signal handler has not specified the 232.Dv SA_RESTART 233(see 234.Xr sigaction 2 ) . 235.El 236.Pp 237When a shared lock has been set on a segment of a file, 238other processes can set shared locks on that segment 239or a portion of it. 240A shared lock prevents any other process from setting an exclusive 241lock on any portion of the protected area. 242A request for a shared lock fails if the file descriptor was not 243opened with read access. 244.Pp 245An exclusive lock prevents any other process from setting a shared lock or 246an exclusive lock on any portion of the protected area. 247A request for an exclusive lock fails if the file was not 248opened with write access. 249.Pp 250The value of 251.Fa l_whence 252is 253.Dv SEEK_SET , 254.Dv SEEK_CUR , 255or 256.Dv SEEK_END 257to indicate that the relative offset, 258.Fa l_start 259bytes, will be measured from the start of the file, 260current position, or end of the file, respectively. 261The value of 262.Fa l_len 263is the number of consecutive bytes to be locked. 264If 265.Fa l_len 266is negative, 267.Fa l_start 268means end edge of the region. 269The 270.Fa l_pid 271field is only used with 272.Dv F_GETLK 273to return the process ID of the process holding a blocking lock. 274After a successful 275.Dv F_GETLK 276request, the value of 277.Fa l_whence 278is 279.Dv SEEK_SET . 280.Pp 281Locks may start and extend beyond the current end of a file, 282but may not start or extend before the beginning of the file. 283A lock is set to extend to the largest possible value of the 284file offset for that file if 285.Fa l_len 286is set to zero. 287If 288.Fa l_whence 289and 290.Fa l_start 291point to the beginning of the file, and 292.Fa l_len 293is zero, the entire file is locked. 294If an application wishes only to do entire file locking, the 295.Xr flock 2 296system call is much more efficient. 297.Pp 298There is at most one type of lock set for each byte in the file. 299Before a successful return from an 300.Dv F_SETLK 301or an 302.Dv F_SETLKW 303request when the calling process has previously existing locks 304on bytes in the region specified by the request, 305the previous lock type for each byte in the specified 306region is replaced by the new lock type. 307As specified above under the descriptions 308of shared locks and exclusive locks, an 309.Dv F_SETLK 310or an 311.Dv F_SETLKW 312request fails or blocks respectively when another process has existing 313locks on bytes in the specified region and the type of any of those 314locks conflicts with the type specified in the request. 315.Pp 316This interface follows the completely stupid semantics of System V and 317.St -p1003.1-88 318that require that all locks associated with a file for a given process are 319removed when 320.Em any 321file descriptor for that file is closed by that process. 322This semantic means that applications must be aware of any files that 323a subroutine library may access. 324For example if an application for updating the password file locks the 325password file database while making the update, and then calls 326.Xr getpwnam 3 327to retrieve a record, 328the lock will be lost because 329.Xr getpwnam 3 330opens, reads, and closes the password database. 331The database close will release all locks that the process has 332associated with the database, even if the library routine never 333requested a lock on the database. 334Another minor semantic problem with this interface is that 335locks are not inherited by a child process created using the 336.Xr fork 2 337system call. 338The 339.Xr flock 2 340interface has much more rational last close semantics and 341allows locks to be inherited by child processes. 342The 343.Xr flock 2 344system call is recommended for applications that want to ensure the integrity 345of their locks when using library routines or wish to pass locks 346to their children. 347.Pp 348The 349.Fn fcntl , 350.Xr flock 2 , 351and 352.Xr lockf 3 353locks are compatible. 354Processes using different locking interfaces can cooperate 355over the same file safely. 356However, only one of such interfaces should be used within 357the same process. 358If a file is locked by a process through 359.Xr flock 2 , 360any record within the file will be seen as locked 361from the viewpoint of another process using 362.Fn fcntl 363or 364.Xr lockf 3 , 365and vice versa. 366Note that 367.Fn fcntl F_GETLK 368returns \-1 in 369.Fa l_pid 370if the process holding a blocking lock previously locked the 371file descriptor by 372.Xr flock 2 . 373.Pp 374All locks associated with a file for a given process are 375removed when the process terminates. 376.Pp 377All locks obtained before a call to 378.Xr execve 2 379remain in effect until the new program releases them. 380If the new program does not know about the locks, they will not be 381released until the program exits. 382.Pp 383A potential for deadlock occurs if a process controlling a locked region 384is put to sleep by attempting to lock the locked region of another process. 385This implementation detects that sleeping until a locked region is unlocked 386would cause a deadlock and fails with an 387.Er EDEADLK 388error. 389.Sh RETURN VALUES 390Upon successful completion, the value returned depends on 391.Fa cmd 392as follows: 393.Bl -tag -width F_GETOWNX -offset indent 394.It Dv F_DUPFD 395A new file descriptor. 396.It Dv F_GETFD 397Value of flag (only the low-order bit is defined). 398.It Dv F_GETFL 399Value of flags. 400.It Dv F_GETOWN 401Value of file descriptor owner. 402.It other 403Value other than -1. 404.El 405.Pp 406Otherwise, a value of -1 is returned and 407.Va errno 408is set to indicate the error. 409.Sh ERRORS 410The 411.Fn fcntl 412system call will fail if: 413.Bl -tag -width Er 414.It Bq Er EAGAIN 415The argument 416.Fa cmd 417is 418.Dv F_SETLK , 419the type of lock 420.Pq Fa l_type 421is a shared lock 422.Pq Dv F_RDLCK 423or exclusive lock 424.Pq Dv F_WRLCK , 425and the segment of a file to be locked is already 426exclusive-locked by another process; 427or the type is an exclusive lock and some portion of the 428segment of a file to be locked is already shared-locked or 429exclusive-locked by another process. 430.It Bq Er EBADF 431The 432.Fa fd 433argument 434is not a valid open file descriptor. 435.Pp 436The argument 437.Fa cmd 438is 439.Dv F_SETLK 440or 441.Dv F_SETLKW , 442the type of lock 443.Pq Fa l_type 444is a shared lock 445.Pq Dv F_RDLCK , 446and 447.Fa fd 448is not a valid file descriptor open for reading. 449.Pp 450The argument 451.Fa cmd 452is 453.Dv F_SETLK 454or 455.Dv F_SETLKW , 456the type of lock 457.Pq Fa l_type 458is an exclusive lock 459.Pq Dv F_WRLCK , 460and 461.Fa fd 462is not a valid file descriptor open for writing. 463.It Bq Er EDEADLK 464The argument 465.Fa cmd 466is 467.Dv F_SETLKW , 468and a deadlock condition was detected. 469.It Bq Er EINTR 470The argument 471.Fa cmd 472is 473.Dv F_SETLKW , 474and the system call was interrupted by a signal. 475.It Bq Er EINVAL 476The 477.Fa cmd 478argument 479is 480.Dv F_DUPFD 481and 482.Fa arg 483is negative or greater than the maximum allowable number 484(see 485.Xr getdtablesize 2 ) . 486.Pp 487The argument 488.Fa cmd 489is 490.Dv F_GETLK , 491.Dv F_SETLK 492or 493.Dv F_SETLKW 494and the data to which 495.Fa arg 496points is not valid. 497.It Bq Er EMFILE 498The argument 499.Fa cmd 500is 501.Dv F_DUPFD 502and the maximum number of file descriptors permitted for the 503process are already in use, 504or no file descriptors greater than or equal to 505.Fa arg 506are available. 507.It Bq Er ENOLCK 508The argument 509.Fa cmd 510is 511.Dv F_SETLK 512or 513.Dv F_SETLKW , 514and satisfying the lock or unlock request would result in the 515number of locked regions in the system exceeding a system-imposed limit. 516.It Bq Er EOPNOTSUPP 517The argument 518.Fa cmd 519is 520.Dv F_GETLK , 521.Dv F_SETLK 522or 523.Dv F_SETLKW 524and 525.Fa fd 526refers to a file for which locking is not supported. 527.It Bq Er EOVERFLOW 528The argument 529.Fa cmd 530is 531.Dv F_GETLK , 532.Dv F_SETLK 533or 534.Dv F_SETLKW 535and an 536.Fa off_t 537calculation overflowed. 538.It Bq Er EPERM 539The 540.Fa cmd 541argument 542is 543.Dv F_SETOWN 544and 545the process ID or process group given as an argument is in a 546different session than the caller. 547.It Bq Er ESRCH 548The 549.Fa cmd 550argument 551is 552.Dv F_SETOWN 553and 554the process ID given as argument is not in use. 555.El 556.Pp 557In addition, if 558.Fa fd 559refers to a descriptor open on a terminal device (as opposed to a 560descriptor open on a socket), a 561.Fa cmd 562of 563.Dv F_SETOWN 564can fail for the same reasons as in 565.Xr tcsetpgrp 3 , 566and a 567.Fa cmd 568of 569.Dv F_GETOWN 570for the reasons as stated in 571.Xr tcgetpgrp 3 . 572.Sh SEE ALSO 573.Xr close 2 , 574.Xr execve 2 , 575.Xr flock 2 , 576.Xr getdtablesize 2 , 577.Xr open 2 , 578.Xr sigvec 2 , 579.Xr lockf 3 , 580.Xr tcgetpgrp 3 , 581.Xr tcsetpgrp 3 582.Sh HISTORY 583The 584.Fn fcntl 585system call appeared in 586.Bx 4.2 . 587