1.\" Copyright (c) 1983, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94 29.\" $FreeBSD: src/lib/libc/sys/fcntl.2,v 1.16.2.13 2002/07/22 15:15:16 bde Exp $ 30.\" 31.Dd January 12, 1994 32.Dt FCNTL 2 33.Os 34.Sh NAME 35.Nm fcntl 36.Nd file control 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In fcntl.h 41.Ft int 42.Fn fcntl "int fd" "int cmd" "..." 43.Sh DESCRIPTION 44.Fn Fcntl 45provides for control over descriptors. 46The argument 47.Fa fd 48is a descriptor to be operated on by 49.Fa cmd 50as described below. Depending on the value of 51.Fa cmd , 52.Nm 53can take an additional third argument 54.Fa "int arg" . 55.Bl -tag -width F_GETOWNX 56.It Dv F_DUPFD 57Return a new descriptor as follows: 58.Pp 59.Bl -bullet -compact -offset 4n 60.It 61Lowest numbered available descriptor greater than or equal to 62.Fa arg . 63.It 64Same object references as the original descriptor. 65.It 66New descriptor shares the same file offset if the object 67was a file. 68.It 69Same access mode (read, write or read/write). 70.It 71Same file status flags (i.e., both file descriptors 72share the same file status flags). 73.It 74The close-on-exec flag associated with the new file descriptor 75is set to remain open across 76.Xr execve 2 77system calls. 78.El 79.It Dv F_GETFD 80Get the close-on-exec flag associated with the file descriptor 81.Fa fd 82as 83.Dv FD_CLOEXEC . 84If the returned value ANDed with 85.Dv FD_CLOEXEC 86is 0, 87the file will remain open across 88.Fn exec , 89otherwise the file will be closed upon execution of 90.Fn exec 91.Fa ( arg 92is ignored). 93.It Dv F_SETFD 94Set the close-on-exec flag associated with 95.Fa fd 96to 97.Fa arg , 98where 99.Fa arg 100is either 0 or 101.Dv FD_CLOEXEC , 102as described 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 . 110.It Dv F_GETOWN 111Get the process ID or process group 112currently receiving 113.Dv SIGIO 114and 115.Dv SIGURG 116signals; process groups are returned 117as negative values 118.Fa ( arg 119is ignored). 120.It Dv F_SETOWN 121Set the process or process group 122to receive 123.Dv SIGIO 124and 125.Dv SIGURG 126signals; 127process groups are specified by supplying 128.Fa arg 129as negative, otherwise 130.Fa arg 131is interpreted as a process ID. 132.El 133.Pp 134The flags for the 135.Dv F_GETFL 136and 137.Dv F_SETFL 138flags are as follows: 139.Bl -tag -width O_NONBLOCKX 140.It Dv O_NONBLOCK 141Non-blocking I/O; if no data is available to a 142.Xr read 2 143call, or if a 144.Xr write 2 145operation would block, 146the read or write call returns -1 with the error 147.Er EAGAIN . 148.It Dv O_APPEND 149Force each write to append at the end of file; 150corresponds to the 151.Dv O_APPEND 152flag of 153.Xr open 2 . 154.It Dv O_DIRECT 155Minimize or eliminate the cache effects of reading and writing. The system 156will attempt to avoid caching the data you read or write. If it cannot 157avoid caching the data, it will minimize the impact the data has on the cache. 158Use of this flag can drastically reduce performance if not used with care. 159.It Dv O_ASYNC 160Enable the 161.Dv SIGIO 162signal to be sent to the process group 163when I/O is possible, e.g., 164upon availability of data to be read. 165.El 166.Pp 167Several commands are available for doing advisory file locking; 168they all operate on the following structure: 169.Bd -literal 170struct flock { 171 off_t l_start; /* starting offset */ 172 off_t l_len; /* len = 0 means until end of file */ 173 pid_t l_pid; /* lock owner */ 174 short l_type; /* lock type: read/write, etc. */ 175 short l_whence; /* type of l_start */ 176}; 177.Ed 178The commands available for advisory record locking are as follows: 179.Bl -tag -width F_SETLKWX 180.It Dv F_GETLK 181Get the first lock that blocks the lock description pointed to by the 182third argument, 183.Fa arg , 184taken as a pointer to a 185.Fa "struct flock" 186(see above). 187The information retrieved overwrites the information passed to 188.Fn fcntl 189in the 190.Fa flock 191structure. 192If no lock is found that would prevent this lock from being created, 193the structure is left unchanged by this function call except for the 194lock type which is set to 195.Dv F_UNLCK . 196.It Dv F_SETLK 197Set or clear a file segment lock according to the lock description 198pointed to by the third argument, 199.Fa arg , 200taken as a pointer to a 201.Fa "struct flock" 202(see above). 203.Dv F_SETLK 204is used to establish shared (or read) locks 205.Pq Dv F_RDLCK 206or exclusive (or write) locks, 207.Pq Dv F_WRLCK , 208as well as remove either type of lock 209.Pq Dv F_UNLCK . 210If a shared or exclusive lock cannot be set, 211.Fn fcntl 212returns immediately with 213.Er EAGAIN . 214.It Dv F_SETLKW 215This command is the same as 216.Dv F_SETLK 217except that if a shared or exclusive lock is blocked by other locks, 218the process waits until the request can be satisfied. 219If a signal that is to be caught is received while 220.Fn fcntl 221is waiting for a region, the 222.Fn fcntl 223will be interrupted if the signal handler has not specified the 224.Dv SA_RESTART 225(see 226.Xr sigaction 2 ) . 227.El 228.Pp 229When a shared lock has been set on a segment of a file, 230other processes can set shared locks on that segment 231or a portion of it. 232A shared lock prevents any other process from setting an exclusive 233lock on any portion of the protected area. 234A request for a shared lock fails if the file descriptor was not 235opened with read access. 236.Pp 237An exclusive lock prevents any other process from setting a shared lock or 238an exclusive lock on any portion of the protected area. 239A request for an exclusive lock fails if the file was not 240opened with write access. 241.Pp 242The value of 243.Fa l_whence 244is 245.Dv SEEK_SET , 246.Dv SEEK_CUR , 247or 248.Dv SEEK_END 249to indicate that the relative offset, 250.Fa l_start 251bytes, will be measured from the start of the file, 252current position, or end of the file, respectively. 253The value of 254.Fa l_len 255is the number of consecutive bytes to be locked. 256If 257.Fa l_len 258is negative, the result is undefined. 259The 260.Fa l_pid 261field is only used with 262.Dv F_GETLK 263to return the process ID of the process holding a blocking lock. 264After a successful 265.Dv F_GETLK 266request, the value of 267.Fa l_whence 268is 269.Dv SEEK_SET . 270.Pp 271Locks may start and extend beyond the current end of a file, 272but may not start or extend before the beginning of the file. 273A lock is set to extend to the largest possible value of the 274file offset for that file if 275.Fa l_len 276is set to zero. 277If 278.Fa l_whence 279and 280.Fa l_start 281point to the beginning of the file, and 282.Fa l_len 283is zero, the entire file is locked. 284If an application wishes only to do entire file locking, the 285.Xr flock 2 286system call is much more efficient. 287.Pp 288There is at most one type of lock set for each byte in the file. 289Before a successful return from an 290.Dv F_SETLK 291or an 292.Dv F_SETLKW 293request when the calling process has previously existing locks 294on bytes in the region specified by the request, 295the previous lock type for each byte in the specified 296region is replaced by the new lock type. 297As specified above under the descriptions 298of shared locks and exclusive locks, an 299.Dv F_SETLK 300or an 301.Dv F_SETLKW 302request fails or blocks respectively when another process has existing 303locks on bytes in the specified region and the type of any of those 304locks conflicts with the type specified in the request. 305.Pp 306This interface follows the completely stupid semantics of System V and 307.St -p1003.1-88 308that require that all locks associated with a file for a given process are 309removed when 310.Em any 311file descriptor for that file is closed by that process. 312This semantic means that applications must be aware of any files that 313a subroutine library may access. 314For example if an application for updating the password file locks the 315password file database while making the update, and then calls 316.Xr getpwnam 3 317to retrieve a record, 318the lock will be lost because 319.Xr getpwnam 3 320opens, reads, and closes the password database. 321The database close will release all locks that the process has 322associated with the database, even if the library routine never 323requested a lock on the database. 324Another minor semantic problem with this interface is that 325locks are not inherited by a child process created using the 326.Xr fork 2 327function. 328The 329.Xr flock 2 330interface has much more rational last close semantics and 331allows locks to be inherited by child processes. 332.Xr Flock 2 333is recommended for applications that want to ensure the integrity 334of their locks when using library routines or wish to pass locks 335to their children. 336Note that 337.Xr flock 2 338and 339.Xr fcntl 2 340locks may be safely used concurrently but 341.Fn fcntl F_GETLK 342returns \-1 in 343.Fa l_pid 344if the process holding a blocking lock previously locked the 345file descriptor by 346.Xr flock 2 . 347.Pp 348All locks associated with a file for a given process are 349removed when the process terminates. 350.Pp 351All locks obtained before a call to 352.Xr execve 2 353remain in effect until the new program releases them. 354If the new program does not know about the locks, they will not be 355released until the program exits. 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 cmd 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 \&Fd 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 fd 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 fd 433is not a valid file descriptor open for writing. 434.It Bq Er EDEADLK 435The argument 436.Fa cmd 437is 438.Dv F_SETLKW , 439and a deadlock condition was detected. 440.It Bq Er EINTR 441The argument 442.Fa cmd 443is 444.Dv F_SETLKW , 445and the function was interrupted by a signal. 446.It Bq Er EINVAL 447.Fa Cmd 448is 449.Dv F_DUPFD 450and 451.Fa arg 452is negative or greater than the maximum allowable number 453(see 454.Xr getdtablesize 2 ) . 455.Pp 456The argument 457.Fa cmd 458is 459.Dv F_GETLK , 460.Dv F_SETLK , 461or 462.Dv F_SETLKW 463and the data to which 464.Fa arg 465points is not valid, or 466.Fa fd 467refers to a file that does not support locking. 468.It Bq Er EMFILE 469The argument 470.Fa cmd 471is 472.Dv F_DUPFD 473and the maximum number of file descriptors permitted for the 474process are already in use, 475or no file descriptors greater than or equal to 476.Fa arg 477are available. 478.It Bq Er ENOLCK 479The argument 480.Fa cmd 481is 482.Dv F_SETLK 483or 484.Dv F_SETLKW , 485and satisfying the lock or unlock request would result in the 486number of locked regions in the system exceeding a system-imposed limit. 487.It Bq Er EPERM 488.Fa Cmd 489is 490.Dv F_SETOWN 491and 492the process ID or process group given as an argument is in a 493different session than the caller. 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.Pp 502In addition, if 503.Fa fd 504refers to a descriptor open on a terminal device (as opposed to a 505descriptor open on a socket), a 506.Fa cmd 507of 508.Dv F_SETOWN 509can fail for the same reasons as in 510.Xr tcsetpgrp 3 , 511and a 512.Fa cmd 513of 514.Dv F_GETOWN 515for the reasons as stated in 516.Xr tcgetpgrp 3 . 517.Sh SEE ALSO 518.Xr close 2 , 519.Xr execve 2 , 520.Xr flock 2 , 521.Xr getdtablesize 2 , 522.Xr open 2 , 523.Xr sigaction 2 , 524.Xr tcgetpgrp 3 , 525.Xr tcsetpgrp 3 526.Sh HISTORY 527The 528.Fn fcntl 529function call appeared in 530.Bx 4.2 . 531