1.\" $NetBSD: fcntl.2,v 1.37 2010/05/17 12:16:43 jruoho 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 May 17, 2010 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 cleared 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.Sh COMPATIBILITY 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. 337.Pp 338Another minor semantic problem with this interface is that 339locks are not inherited by a child process created using the 340.Xr fork 2 341function. 342The 343.Xr flock 2 344interface has much more rational last close semantics and 345allows locks to be inherited by child processes. 346Calling 347.Xr flock 2 348is recommended for applications that want to ensure the integrity 349of their locks when using library routines or wish to pass locks 350to their children. 351Note that 352.Xr flock 2 353and 354.Nm 355locks may be safely used concurrently. 356.Pp 357All locks associated with a file for a given process are 358removed when the process terminates. 359.Pp 360A potential for deadlock occurs if a process controlling a locked region 361is put to sleep by attempting to lock the locked region of another process. 362This implementation detects that sleeping until a locked region is unlocked 363would cause a deadlock and fails with an 364.Er EDEADLK 365error. 366.Sh RETURN VALUES 367Upon successful completion, the value returned depends on 368.Fa cmd 369as follows: 370.Bl -tag -width F_GETOWNX -offset indent 371.It Dv F_DUPFD 372A new file descriptor. 373.It Dv F_GETFD 374Value of flag (only the low-order bit is defined). 375.It Dv F_GETFL 376Value of flags. 377.It Dv F_GETOWN 378Value of file descriptor owner. 379.It Dv F_MAXFD 380Value of the highest file descriptor open by the process. 381.It other 382Value other than \-1. 383.El 384.Pp 385Otherwise, a value of \-1 is returned and 386.Va errno 387is set to indicate the error. 388.Sh ERRORS 389.Fn fcntl 390will fail if: 391.Bl -tag -width Er 392.It Bq Er EAGAIN 393The argument 394.Fa arg 395is 396.Dv F_SETLK , 397the type of lock 398.Pq Fa l_type 399is a shared lock 400.Pq Dv F_RDLCK 401or exclusive lock 402.Pq Dv F_WRLCK , 403and the segment of a file to be locked is already 404exclusive-locked by another process; 405or the type is an exclusive lock and some portion of the 406segment of a file to be locked is already shared-locked or 407exclusive-locked by another process. 408.It Bq Er EBADF 409.Fa fildes 410is not a valid open file descriptor. 411.Pp 412The argument 413.Fa cmd 414is 415.Dv F_SETLK 416or 417.Dv F_SETLKW , 418the type of lock 419.Pq Fa l_type 420is a shared lock 421.Pq Dv F_RDLCK , 422and 423.Fa fildes 424is not a valid file descriptor open for reading. 425.Pp 426The argument 427.Fa cmd 428is 429.Dv F_SETLK 430or 431.Dv F_SETLKW , 432the type of lock 433.Pq Fa l_type 434is an exclusive lock 435.Pq Dv F_WRLCK , 436and 437.Fa fildes 438is not a valid file descriptor open for writing. 439.It Bq Er EDEADLK 440The argument 441.Fa cmd 442is 443.Dv F_SETLKW , 444and a deadlock condition was detected. 445.It Bq Er EINTR 446The argument 447.Fa cmd 448is 449.Dv F_SETLKW , 450and the function was interrupted by a signal. 451.It Bq Er EINVAL 452The argument 453.Fa cmd 454is invalid. 455.Pp 456The argument 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 ENFILE 489.Fa cmd 490is 491.Dv F_DUPFD 492and system-wide the maximum allowed number of file descriptors are 493currently open. 494.It Bq Er ENOLCK 495The argument 496.Fa cmd 497is 498.Dv F_SETLK 499or 500.Dv F_SETLKW , 501and satisfying the lock or unlock request would result in the 502number of locked regions in the system exceeding a system-imposed limit. 503.It Bq Er ESRCH 504.Fa cmd 505is 506.Dv F_SETOWN 507and 508the process ID given as argument is not in use. 509.El 510.Sh SEE ALSO 511.Xr close 2 , 512.Xr execve 2 , 513.Xr flock 2 , 514.Xr open 2 , 515.Xr sigaction 2 , 516.Xr getdtablesize 3 517.Sh STANDARDS 518The 519.Fn fcntl 520function conforms to 521.St -p1003.1-90 . 522.Sh HISTORY 523The 524.Fn fcntl 525function call appeared in 526.Bx 4.2 . 527