1.\" $NetBSD: fcntl.2,v 1.28 2003/04/16 13:34:51 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.In fcntl.h 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 185.Pp 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.Nm 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 function call except for the 202lock type 203.Fa l_type , 204which is set to 205.Dv F_UNLCK . 206.It Dv F_SETLK 207Set or clear a file segment lock according to the lock description 208pointed to by the third argument, 209.Fa arg , 210taken as a pointer to a 211.Fa "struct flock" 212(see above). 213As specified by the value of 214.Fa l_type , 215.Dv F_SETLK 216is used to establish shared (or read) locks 217.Pq Dv F_RDLCK 218or exclusive (or write) locks, 219.Pq Dv F_WRLCK , 220as well as remove either type of lock 221.Pq Dv F_UNLCK . 222If a shared or exclusive lock cannot be set, 223.Nm 224returns immediately with 225.Er EAGAIN . 226.It Dv F_SETLKW 227This command is the same as 228.Dv F_SETLK 229except that if a shared or exclusive lock is blocked by other locks, 230the process waits until the request can be satisfied. 231If a signal that is to be caught is received while 232.Nm 233is waiting for a region, the 234.Nm 235will be interrupted if the signal handler has not specified the 236.Dv SA_RESTART 237(see 238.Xr sigaction 2 ) . 239.El 240.Pp 241When a shared lock has been set on a segment of a file, 242other processes can set shared locks on that segment 243or a portion of it. 244A shared lock prevents any other process from setting an exclusive 245lock on any portion of the protected area. 246A request for a shared lock fails if the file descriptor was not 247opened with read access. 248.Pp 249An exclusive lock prevents any other process from setting a shared lock or 250an exclusive lock on any portion of the protected area. 251A request for an exclusive lock fails if the file was not 252opened with write access. 253.Pp 254The value of 255.Fa l_whence 256is 257.Dv SEEK_SET , 258.Dv SEEK_CUR , 259or 260.Dv SEEK_END 261to indicate that the relative offset, 262.Fa l_start 263bytes, will be measured from the start of the file, 264current position, or end of the file, respectively. 265The value of 266.Fa l_len 267is the number of consecutive bytes to be locked. 268If 269.Fa l_len 270is negative, the result is undefined. 271The 272.Fa l_pid 273field is only used with 274.Dv F_GETLK 275to return the process ID of the process holding a blocking lock. 276After a successful 277.Dv F_GETLK 278request, the value of 279.Fa l_whence 280is 281.Dv SEEK_SET . 282.Pp 283Locks may start and extend beyond the current end of a file, 284but may not start or extend before the beginning of the file. 285A lock is set to extend to the largest possible value of the 286file offset for that file if 287.Fa l_len 288is set to zero. 289If 290.Fa l_whence 291and 292.Fa l_start 293point to the beginning of the file, and 294.Fa l_len 295is zero, the entire file is locked. 296If an application wishes only to do entire file locking, the 297.Xr flock 2 298system call is much more efficient. 299.Pp 300There is at most one type of lock set for each byte in the file. 301Before a successful return from an 302.Dv F_SETLK 303or an 304.Dv F_SETLKW 305request when the calling process has previously existing locks 306on bytes in the region specified by the request, 307the previous lock type for each byte in the specified 308region is replaced by the new lock type. 309As specified above under the descriptions 310of shared locks and exclusive locks, an 311.Dv F_SETLK 312or an 313.Dv F_SETLKW 314request fails or blocks respectively when another process has existing 315locks on bytes in the specified region and the type of any of those 316locks conflicts with the type specified in the request. 317.Pp 318This interface follows the completely stupid semantics of 319.At V 320and 321.St -p1003.1-88 322that require that all locks associated with a file for a given process are 323removed when \fIany\fP file descriptor for that file is closed by that process. 324This semantic means that applications must be aware of any files that 325a subroutine library may access. 326For example if an application for updating the password file locks the 327password file database while making the update, and then calls 328.Xr getpwnam 3 329to retrieve a record, 330the lock will be lost because 331.Xr getpwnam 3 332opens, reads, and closes the password database. 333The database close will release all locks that the process has 334associated with the database, even if the library routine never 335requested a lock on the database. 336Another minor semantic problem with this interface is that 337locks are not inherited by a child process created using the 338.Xr fork 2 339function. 340The 341.Xr flock 2 342interface has much more rational last close semantics and 343allows locks to be inherited by child processes. 344Calling 345.Xr flock 2 346is recommended for applications that want to ensure the integrity 347of their locks when using library routines or wish to pass locks 348to their children. 349Note that 350.Xr flock 2 351and 352.Nm 353locks may be safely used concurrently. 354.Pp 355All locks associated with a file for a given process are 356removed when the process terminates. 357.Pp 358A potential for deadlock occurs if a process controlling a locked region 359is put to sleep by attempting to lock the locked region of another process. 360This implementation detects that sleeping until a locked region is unlocked 361would cause a deadlock and fails with an 362.Er EDEADLK 363error. 364.Sh RETURN VALUES 365Upon successful completion, the value returned depends on 366.Fa cmd 367as follows: 368.Bl -tag -width F_GETOWNX -offset indent 369.It Dv F_DUPFD 370A new file descriptor. 371.It Dv F_GETFD 372Value of flag (only the low-order bit is defined). 373.It Dv F_GETFL 374Value of flags. 375.It Dv F_GETOWN 376Value of file descriptor owner. 377.It other 378Value other than -1. 379.El 380.Pp 381Otherwise, a value of -1 is returned and 382.Va errno 383is set to indicate the error. 384.Sh ERRORS 385.Fn fcntl 386will fail if: 387.Bl -tag -width Er 388.It Bq Er EAGAIN 389The argument 390.Fa arg 391is 392.Dv F_SETLK , 393the type of lock 394.Pq Fa l_type 395is a shared lock 396.Pq Dv F_RDLCK 397or exclusive lock 398.Pq Dv F_WRLCK , 399and the segment of a file to be locked is already 400exclusive-locked by another process; 401or the type is an exclusive lock and some portion of the 402segment of a file to be locked is already shared-locked or 403exclusive-locked by another process. 404.It Bq Er EBADF 405.Fa fildes 406is not a valid open file descriptor. 407.Pp 408The argument 409.Fa cmd 410is 411.Dv F_SETLK 412or 413.Dv F_SETLKW , 414the type of lock 415.Pq Fa l_type 416is a shared lock 417.Pq Dv F_RDLCK , 418and 419.Fa fildes 420is not a valid file descriptor open for reading. 421.Pp 422The argument 423.Fa cmd 424is 425.Dv F_SETLK 426or 427.Dv F_SETLKW , 428the type of lock 429.Pq Fa l_type 430is an exclusive lock 431.Pq Dv F_WRLCK , 432and 433.Fa fildes 434is not a valid file descriptor open for writing. 435.It Bq Er EMFILE 436.Fa cmd 437is 438.Dv F_DUPFD 439and the maximum allowed number of file descriptors are currently 440open. 441.It Bq Er EDEADLK 442The argument 443.Fa cmd 444is 445.Dv F_SETLKW , 446and a deadlock condition was detected. 447.It Bq Er EINTR 448The argument 449.Fa cmd 450is 451.Dv F_SETLKW , 452and the function was interrupted by a signal. 453.It Bq Er EINVAL 454.Fa cmd 455is 456.Dv F_DUPFD 457and 458.Fa arg 459is negative or greater than the maximum allowable number 460(see 461.Xr getdtablesize 3 ) . 462.Pp 463The argument 464.Fa cmd 465is 466.Dv F_GETLK , 467.Dv F_SETLK , 468or 469.Dv F_SETLKW 470and the data to which 471.Fa arg 472points is not valid, or 473.Fa fildes 474refers to a file that does not support locking. 475.It Bq Er EMFILE 476The argument 477.Fa cmd 478is 479.Dv F_DUPFD 480and the maximum number of file descriptors permitted for the 481process are already in use, 482or no file descriptors greater than or equal to 483.Fa arg 484are available. 485.It Bq Er ENOLCK 486The argument 487.Fa cmd 488is 489.Dv F_SETLK 490or 491.Dv F_SETLKW , 492and satisfying the lock or unlock request would result in the 493number of locked regions in the system exceeding a system-imposed limit. 494.It Bq Er ESRCH 495.Fa cmd 496is 497.Dv F_SETOWN 498and 499the process ID given as argument is not in use. 500.El 501.Sh SEE ALSO 502.Xr close 2 , 503.Xr execve 2 , 504.Xr flock 2 , 505.Xr open 2 , 506.Xr sigaction 2 , 507.Xr getdtablesize 3 508.Sh STANDARDS 509The 510.Fn fcntl 511function conforms to 512.St -p1003.1-90 . 513.Sh HISTORY 514The 515.Fn fcntl 516function call appeared in 517.Bx 4.2 . 518