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