1.\" $NetBSD: fcntl.2,v 1.22 2002/02/08 01:28:17 ross 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 . 90If the low-order bit of the returned value is 0, 91the file will remain open across 92.Fn exec , 93otherwise the file will be closed upon execution of 94.Fn exec 95.Fa ( arg 96is ignored). 97.It Dv F_SETFD 98Set the close-on-exec flag associated with 99.Fa fd 100to the low order bit of 101.Fa arg 102(0 or 1 as above). 103.It Dv F_GETFL 104Get descriptor status flags, as described below 105.Fa ( arg 106is ignored). 107.It Dv F_SETFL 108Set descriptor status flags to 109.Fa arg , 110which is interpreted as an int. 111.It Dv F_GETOWN 112Get the process ID or process group 113currently receiving 114.Dv SIGIO 115and 116.Dv SIGURG 117signals; process groups are returned 118as negative values 119.Fa ( arg 120is ignored). 121.It Dv F_SETOWN 122Set the process or process group 123to receive 124.Dv SIGIO 125and 126.Dv SIGURG 127signals; 128process groups are specified by supplying 129.Fa arg 130as negative, otherwise 131.Fa arg 132is interpreted as a process ID. 133The argument 134.Fa arg 135is interpreted as an int. 136.El 137.Pp 138The flags for the 139.Dv F_GETFL 140and 141.Dv F_SETFL 142flags are as follows: 143.Bl -tag -width O_NONBLOCKX 144.It Dv O_NONBLOCK 145Non-blocking I/O; if no data is available to a 146.Xr read 2 147call, or if a 148.Xr write 2 149operation would block, 150the read or write call returns -1 with the error 151.Er EAGAIN . 152.It Dv O_APPEND 153Force each write to append at the end of file; 154corresponds to the 155.Dv O_APPEND 156flag of 157.Xr open 2 . 158.It Dv O_ASYNC 159Enable the 160.Dv SIGIO 161signal to be sent to the process group 162when I/O is possible, e.g., 163upon availability of data to be read. 164.El 165.Pp 166Several commands are available for doing advisory file locking; 167they all operate on the following structure: 168.Bd -literal 169struct flock { 170 off_t l_start; /* starting offset */ 171 off_t l_len; /* len = 0 means until end of file */ 172 pid_t l_pid; /* lock owner */ 173 short l_type; /* lock type: read/write, etc. */ 174 short l_whence; /* type of l_start */ 175}; 176.Ed 177The commands available for advisory record locking are as follows: 178.Bl -tag -width F_SETLKWX 179.It Dv F_GETLK 180Get the first lock that blocks the lock description pointed to by the 181third argument, 182.Fa arg , 183taken as a pointer to a 184.Fa "struct flock" 185(see above). 186The information retrieved overwrites the information passed to 187.Nm 188in the 189.Fa flock 190structure. 191If no lock is found that would prevent this lock from being created, 192the structure is left unchanged by this function call except for the 193lock type 194.Fa l_type , 195which is set to 196.Dv F_UNLCK . 197.It Dv F_SETLK 198Set or clear a file segment lock according to the lock description 199pointed to by the third argument, 200.Fa arg , 201taken as a pointer to a 202.Fa "struct flock" 203(see above). 204As specified by the value of 205.Fa l_type , 206.Dv F_SETLK 207is used to establish shared (or read) locks 208.Dv (F_RDLCK) 209or exclusive (or write) locks, 210.Dv (F_WRLCK) , 211as well as remove either type of lock 212.Dv (F_UNLCK) . 213If a shared or exclusive lock cannot be set, 214.Nm 215returns immediately with 216.Er EAGAIN . 217.It Dv F_SETLKW 218This command is the same as 219.Dv F_SETLK 220except that if a shared or exclusive lock is blocked by other locks, 221the process waits until the request can be satisfied. 222If a signal that is to be caught is received while 223.Nm 224is waiting for a region, the 225.Nm 226will be interrupted if the signal handler has not specified the 227.Dv SA_RESTART 228(see 229.Xr sigaction 2 ) . 230.El 231.Pp 232When a shared lock has been set on a segment of a file, 233other processes can set shared locks on that segment 234or a portion of it. 235A shared lock prevents any other process from setting an exclusive 236lock on any portion of the protected area. 237A request for a shared lock fails if the file descriptor was not 238opened with read access. 239.Pp 240An exclusive lock prevents any other process from setting a shared lock or 241an exclusive lock on any portion of the protected area. 242A request for an exclusive lock fails if the file was not 243opened with write access. 244.Pp 245The value of 246.Fa l_whence 247is 248.Dv SEEK_SET , 249.Dv SEEK_CUR , 250or 251.Dv SEEK_END 252to indicate that the relative offset, 253.Fa l_start 254bytes, will be measured from the start of the file, 255current position, or end of the file, respectively. 256The value of 257.Fa l_len 258is the number of consecutive bytes to be locked. 259If 260.Fa l_len 261is negative, the result is undefined. 262The 263.Fa l_pid 264field is only used with 265.Dv F_GETLK 266to return the process ID of the process holding a blocking lock. 267After a successful 268.Dv F_GETLK 269request, the value of 270.Fa l_whence 271is 272.Dv SEEK_SET . 273.Pp 274Locks may start and extend beyond the current end of a file, 275but may not start or extend before the beginning of the file. 276A lock is set to extend to the largest possible value of the 277file offset for that file if 278.Fa l_len 279is set to zero. If 280.Fa l_whence 281and 282.Fa l_start 283point to the beginning of the file, and 284.Fa l_len 285is zero, the entire file is locked. 286If an application wishes only to do entire file locking, the 287.Xr flock 2 288system call is much more efficient. 289.Pp 290There is at most one type of lock set for each byte in the file. 291Before a successful return from an 292.Dv F_SETLK 293or an 294.Dv F_SETLKW 295request when the calling process has previously existing locks 296on bytes in the region specified by the request, 297the previous lock type for each byte in the specified 298region is replaced by the new lock type. 299As specified above under the descriptions 300of shared locks and exclusive locks, an 301.Dv F_SETLK 302or an 303.Dv F_SETLKW 304request fails or blocks respectively when another process has existing 305locks on bytes in the specified region and the type of any of those 306locks conflicts with the type specified in the request. 307.Pp 308This interface follows the completely stupid semantics of 309.At V 310and 311.St -p1003.1-88 312that require that all locks associated with a file for a given process are 313removed when \fIany\fP file descriptor for that file is closed by that process. 314This semantic means that applications must be aware of any files that 315a subroutine library may access. 316For example if an application for updating the password file locks the 317password file database while making the update, and then calls 318.Xr getpwnam 3 319to retrieve a record, 320the lock will be lost because 321.Xr getpwnam 3 322opens, reads, and closes the password database. 323The database close will release all locks that the process has 324associated with the database, even if the library routine never 325requested a lock on the database. 326Another minor semantic problem with this interface is that 327locks are not inherited by a child process created using the 328.Xr fork 2 329function. 330The 331.Xr flock 2 332interface has much more rational last close semantics and 333allows locks to be inherited by child processes. 334Calling 335.Xr flock 2 336is recommended for applications that want to ensure the integrity 337of their locks when using library routines or wish to pass locks 338to their children. 339Note that 340.Xr flock 2 341and 342.Xr fcntl 2 343locks may be safely used concurrently. 344.Pp 345All locks associated with a file for a given process are 346removed when the process terminates. 347.Pp 348A potential for deadlock occurs if a process controlling a locked region 349is put to sleep by attempting to lock the locked region of another process. 350This implementation detects that sleeping until a locked region is unlocked 351would cause a deadlock and fails with an 352.Er EDEADLK 353error. 354.Sh RETURN VALUES 355Upon successful completion, the value returned depends on 356.Fa cmd 357as follows: 358.Bl -tag -width F_GETOWNX -offset indent 359.It Dv F_DUPFD 360A new file descriptor. 361.It Dv F_GETFD 362Value of flag (only the low-order bit is defined). 363.It Dv F_GETFL 364Value of flags. 365.It Dv F_GETOWN 366Value of file descriptor owner. 367.It other 368Value other than -1. 369.El 370.Pp 371Otherwise, a value of -1 is returned and 372.Va errno 373is set to indicate the error. 374.Sh ERRORS 375.Fn fcntl 376will fail if: 377.Bl -tag -width Er 378.It Bq Er EAGAIN 379The argument 380.Fa arg 381is 382.Dv F_SETLK , 383the type of lock 384.Fa (l_type) 385is a shared lock 386.Dv (F_RDLCK) 387or exclusive lock 388.Dv (F_WRLCK) , 389and the segment of a file to be locked is already 390exclusive-locked by another process; 391or the type is an exclusive lock and some portion of the 392segment of a file to be locked is already shared-locked or 393exclusive-locked by another process. 394.It Bq Er EBADF 395.Fa fildes 396is not a valid open file descriptor. 397.Pp 398The argument 399.Fa cmd 400is 401.Dv F_SETLK 402or 403.Dv F_SETLKW , 404the type of lock 405.Fa (l_type) 406is a shared lock 407.Dv (F_RDLCK) , 408and 409.Fa fildes 410is not a valid file descriptor open for reading. 411.Pp 412The argument 413.Fa cmd 414is 415.Dv F_SETLK 416or 417.Dv F_SETLKW , 418the type of lock 419.Fa (l_type) 420is an exclusive lock 421.Dv (F_WRLCK) , 422and 423.Fa fildes 424is not a valid file descriptor open for writing. 425.It Bq Er EMFILE 426.Fa cmd 427is 428.Dv F_DUPFD 429and the maximum allowed number of file descriptors are currently 430open. 431.It Bq Er EDEADLK 432The argument 433.Fa cmd 434is 435.Dv F_SETLKW , 436and a deadlock condition was detected. 437.It Bq Er EINTR 438The argument 439.Fa cmd 440is 441.Dv F_SETLKW , 442and the function was interrupted by a signal. 443.It Bq Er EINVAL 444.Fa cmd 445is 446.Dv F_DUPFD 447and 448.Fa arg 449is negative or greater than the maximum allowable number 450(see 451.Xr getdtablesize 3 ) . 452.Pp 453The argument 454.Fa cmd 455is 456.Dv F_GETLK , 457.Dv F_SETLK , 458or 459.Dv F_SETLKW 460and the data to which 461.Fa arg 462points is not valid, or 463.Fa fildes 464refers to a file that does not support locking. 465.It Bq Er EMFILE 466The argument 467.Fa cmd 468is 469.Dv F_DUPFD 470and the maximum number of file descriptors permitted for the 471process are already in use, 472or no file descriptors greater than or equal to 473.Fa arg 474are available. 475.It Bq Er ENOLCK 476The argument 477.Fa cmd 478is 479.Dv F_SETLK 480or 481.Dv F_SETLKW , 482and satisfying the lock or unlock request would result in the 483number of locked regions in the system exceeding a system-imposed limit. 484.It Bq Er ESRCH 485.Fa cmd 486is 487.Dv F_SETOWN 488and 489the process ID given as argument is not in use. 490.El 491.Sh SEE ALSO 492.Xr close 2 , 493.Xr execve 2 , 494.Xr flock 2 , 495.Xr open 2 , 496.Xr sigaction 2 , 497.Xr getdtablesize 3 498.Sh STANDARDS 499The 500.Fn fcntl 501function conforms to 502.St -p1003.1-90 . 503.Sh HISTORY 504The 505.Fn fcntl 506function call appeared in 507.Bx 4.2 . 508