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