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