1.\" Copyright (c) 1983, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)fcntl.2 8.2 (Berkeley) 01/12/94 7.\" 8.Dd 9.Dt FCNTL 2 10.Os BSD 4.2 11.Sh NAME 12.Nm fcntl 13.Nd file control 14.Sh SYNOPSIS 15.Fd #include <fcntl.h> 16.Ft int 17.Fn fcntl "int fd" "int cmd" "int arg" 18.Sh DESCRIPTION 19.Fn Fcntl 20provides for control over descriptors. 21The argument 22.Fa fd 23is a descriptor to be operated on by 24.Fa cmd 25as follows: 26.Bl -tag -width F_GETOWNX 27.It Dv F_DUPFD 28Return a new descriptor as follows: 29.Pp 30.Bl -bullet -compact -offset 4n 31.It 32Lowest numbered available descriptor greater than or equal to 33.Fa arg . 34.It 35Same object references as the original descriptor. 36.It 37New descriptor shares the same file offset if the object 38was a file. 39.It 40Same access mode (read, write or read/write). 41.It 42Same file status flags (i.e., both file descriptors 43share the same file status flags). 44.It 45The close-on-exec flag associated with the new file descriptor 46is set to remain open across 47.Xr execv 2 48system calls. 49.El 50.It Dv F_GETFD 51Get the close-on-exec flag associated with the file descriptor 52.Fa fd . 53If the low-order bit of the returned value is 0, 54the file will remain open across 55.Fn exec , 56otherwise the file will be closed upon execution of 57.Fn exec 58.Fa ( arg 59is ignored). 60.It Dv F_SETFD 61Set the close-on-exec flag associated with 62.Fa fd 63to the low order bit of 64.Fa arg 65(0 or 1 as above). 66.It Dv F_GETFL 67Get descriptor status flags, as described below 68.Fa ( arg 69is ignored). 70.It Dv F_SETFL 71Set descriptor status flags to 72.Fa arg . 73.It Dv F_GETOWN 74Get the process ID or process group 75currently receiving 76.Dv SIGIO 77and 78.Dv SIGURG 79signals; process groups are returned 80as negative values 81.Fa ( arg 82is ignored). 83.It Dv F_SETOWN 84Set the process or process group 85to receive 86.Dv SIGIO 87and 88.Dv SIGURG 89signals; 90process groups are specified by supplying 91.Fa arg 92as negative, otherwise 93.Fa arg 94is interpreted as a process ID. 95.El 96.Pp 97The flags for the 98.Dv F_GETFL 99and 100.Dv F_SETFL 101flags are as follows: 102.Bl -tag -width O_NONBLOCKX 103.It Dv O_NONBLOCK 104Non-blocking I/O; if no data is available to a 105.Xr read 106call, or if a 107.Xr write 108operation would block, 109the read or write call returns -1 with the error 110.Er EAGAIN . 111.It Dv O_APPEND 112Force each write to append at the end of file; 113corresponds to the 114.Dv O_APPEND 115flag of 116.Xr open 2 . 117.It Dv O_ASYNC 118Enable the 119.Dv SIGIO 120signal to be sent to the process group 121when I/O is possible, e.g., 122upon availability of data to be read. 123.El 124.Pp 125Several commands are available for doing advisory file locking; 126they all operate on the following structure: 127.ne 7v 128.Bd -literal 129struct flock { 130 off_t l_start; /* starting offset */ 131 off_t l_len; /* len = 0 means until end of file */ 132 pid_t l_pid; /* lock owner */ 133 short l_type; /* lock type: read/write, etc. */ 134 short l_whence; /* type of l_start */ 135}; 136.Ed 137The commands available for advisory record locking are as follows: 138.Bl -tag -width F_SETLKWX 139.It Dv F_GETLK 140Get the first lock that blocks the lock description pointed to by the 141third argument, 142.Fa arg , 143taken as a pointer to a 144.Fa "struct flock" 145(see above). 146The information retrieved overwrites the information passed to 147.Nm fcntl 148in the 149.Fa flock 150structure. 151If no lock is found that would prevent this lock from being created, 152the structure is left unchanged by this function call except for the 153lock type which is set to 154.Dv F_UNLCK . 155.It Dv F_SETLK 156Set or clear a file segment lock according to the lock description 157pointed to by the third argument, 158.Fa arg , 159taken as a pointer to a 160.Fa "struct flock" 161(see above). 162.Dv F_SETLK 163is used to establish shared (or read) locks 164.Dv (F_RDLCK) 165or exclusive (or write) locks, 166.Dv (F_WRLCK) , 167as well as remove either type of lock 168.Dv (F_UNLCK) . 169If a shared or exclusive lock cannot be set, 170.Nm fcntl 171returns immediately with 172.Er EACCES . 173.It Dv F_SETLKW 174This command is the same as 175.Dv F_SETLK 176except that if a shared or exclusive lock is blocked by other locks, 177the process waits until the request can be satisfied. 178If a signal that is to be caught is received while 179.Nm fcntl 180is waiting for a region, the 181.Nm fcntl 182will be interrupted if the signal handler has not specified the 183.Dv SA_RESTART 184(see 185.Xr sigaction 2 ) . 186.El 187.Pp 188When a shared lock has been set on a segment of a file, 189other processes can set shared locks on that segment 190or a portion of it. 191A shared lock prevents any other process from setting an exclusive 192lock on any portion of the protected area. 193A request for a shared lock fails if the file descriptor was not 194opened with read access. 195.Pp 196An exclusive lock prevents any other process from setting a shared lock or 197an exclusive lock on any portion of the protected area. 198A request for an exclusive lock fails if the file was not 199opened with write access. 200.Pp 201The value of 202.Fa l_whence 203is 204.Dv SEEK_SET , 205.Dv SEEK_CUR , 206or 207.Dv SEEK_END 208to indicate that the relative offset, 209.Fa l_start 210bytes, will be measured from the start of the file, 211current position, or end of the file, respectively. 212The value of 213.Fa l_len 214is the number of consecutive bytes to be locked. 215If 216.Fa l_len 217is negative, the result is undefined. 218The 219.Fa l_pid 220field is only used with 221.Dv F_GETLK 222to return the process ID of the process holding a blocking lock. 223After a successful 224.Dv F_GETLK 225request, the value of 226.Fa l_whence 227is 228.Dv SEEK_SET . 229.Pp 230Locks may start and extend beyond the current end of a file, 231but may not start or extend before the beginning of the file. 232A lock is set to extend to the largest possible value of the 233file offset for that file if 234.Fa l_len 235is set to zero. If 236.Fa l_whence 237and 238.Fa l_start 239point to the beginning of the file, and 240.Fa l_len 241is zero, the entire file is locked. 242If an application wishes only to do entire file locking, the 243.Xr flock 2 244system call is much more efficient. 245.Pp 246There is at most one type of lock set for each byte in the file. 247Before a successful return from an 248.Dv F_SETLK 249or an 250.Dv F_SETLKW 251request when the calling process has previously existing locks 252on bytes in the region specified by the request, 253the previous lock type for each byte in the specified 254region is replaced by the new lock type. 255As specified above under the descriptions 256of shared locks and exclusive locks, an 257.Dv F_SETLK 258or an 259.Dv F_SETLKW 260request fails or blocks respectively when another process has existing 261locks on bytes in the specified region and the type of any of those 262locks conflicts with the type specified in the request. 263.Pp 264This interface follows the completely stupid semantics of System V and 265.St -p1003.1-88 266that require that all locks associated with a file for a given process are 267removed when \fIany\fP file descriptor for that file is closed by that process. 268This semantic means that applications must be aware of any files that 269a subroutine library may access. 270For example if an application for updating the password file locks the 271password file database while making the update, and then calls 272.Xr getpwname 3 273to retrieve a record, 274the lock will be lost because 275.Xr getpwname 3 276opens, reads, and closes the password database. 277The database close will release all locks that the process has 278associated with the database, even if the library routine never 279requested a lock on the database. 280Another minor semantic problem with this interface is that 281locks are not inherited by a child process created using the 282.Xr fork 2 283function. 284The 285.Xr flock 2 286interface has much more rational last close semantics and 287allows locks to be inherited by child processes. 288.Xr Flock 2 289is recommended for applications that want to ensure the integrity 290of their locks when using library routines or wish to pass locks 291to their children. 292Note that 293.Xr flock 2 294and 295.Xr fcntl 2 296locks may be safely used concurrently. 297.Pp 298All locks associated with a file for a given process are 299removed when the process terminates. 300.Pp 301A potential for deadlock occurs if a process controlling a locked region 302is put to sleep by attempting to lock the locked region of another process. 303This implementation detects that sleeping until a locked region is unlocked 304would cause a deadlock and fails with an 305.Er EDEADLK 306error. 307.Sh RETURN VALUES 308Upon successful completion, the value returned depends on 309.Fa cmd 310as follows: 311.Bl -tag -width F_GETOWNX -offset indent 312.It Dv F_DUPFD 313A new file descriptor. 314.It Dv F_GETFD 315Value of flag (only the low-order bit is defined). 316.It Dv F_GETFL 317Value of flags. 318.It Dv F_GETOWN 319Value of file descriptor owner. 320.It other 321Value other than -1. 322.El 323.Pp 324Otherwise, a value of -1 is returned and 325.Va errno 326is set to indicate the error. 327.Sh ERRORS 328.Fn Fcntl 329will fail if: 330.Bl -tag -width Er 331.It Bq Er EACCES 332The argument 333.Fa arg 334is 335.Dv F_SETLK , 336the type of lock 337.Fa (l_type) 338is a shared lock 339.Dv (F_RDLCK) 340or exclusive lock 341.Dv (F_WRLCK) , 342and the segment of a file to be locked is already 343exclusive-locked by another process; 344or the type is an exclusive lock and some portion of the 345segment of a file to be locked is already shared-locked or 346exclusive-locked by another process. 347.It Bq Er EBADF 348.Fa Fildes 349is not a valid open file descriptor. 350.Pp 351The argument 352.Fa cmd 353is 354.Dv F_SETLK 355or 356.Dv F_SETLKW , 357the type of lock 358.Fa (l_type) 359is a shared lock 360.Dv (F_RDLCK) , 361and 362.Fa fildes 363is not a valid file descriptor open for reading. 364.Pp 365The argument 366.Fa cmd 367is 368.Dv F_SETLK 369or 370.Dv F_SETLKW , 371the type of lock 372.Fa (l_type) 373is an exclusive lock 374.Dv (F_WRLCK) , 375and 376.Fa fildes 377is not a valid file descriptor open for writing. 378.It Bq Er EMFILE 379.Fa Cmd 380is 381.Dv F_DUPFD 382and the maximum allowed number of file descriptors are currently 383open. 384.It Bq Er EDEADLK 385The argument 386.Fa cmd 387is 388.Dv F_SETLKW , 389and a deadlock condition was detected. 390.It Bq Er EINTR 391The argument 392.Fa cmd 393is 394.Dv F_SETLKW , 395and the function was interrupted by a signal. 396.It Bq Er EINVAL 397.Fa Cmd 398is 399.Dv F_DUPFD 400and 401.Fa arg 402is negative or greater than the maximum allowable number 403(see 404.Xr getdtablesize 2 ) . 405.Pp 406The argument 407.Fa cmd 408is 409.Dv F_GETLK , 410.Dv F_SETLK , 411or 412.Dv F_SETLKW 413and the data to which 414.Fa arg 415points is not valid, or 416.Fa fildes 417refers to a file that does not support locking. 418.It Bq Er EMFILE 419The argument 420.Fa cmd 421is 422.Dv F_DUPED 423and the maximum number of file descriptors permitted for the 424process are already in use, 425or no file descriptors greater than or equal to 426.Fa arg 427are available. 428.It Bq Er ENOLCK 429The argument 430.Fa cmd 431is 432.Dv F_SETLK 433or 434.Dv F_SETLKW , 435and satisfying the lock or unlock request would result in the 436number of locked regions in the system exceeding a system-imposed limit. 437.It Bq Er ESRCH 438.Fa Cmd 439is 440.Dv F_SETOWN 441and 442the process ID given as argument is not in use. 443.El 444.Sh SEE ALSO 445.Xr close 2 , 446.Xr execve 2 , 447.Xr flock 2 , 448.Xr getdtablesize 2 , 449.Xr open 2 , 450.Xr sigvec 2 451.Sh HISTORY 452The 453.Nm 454function call appeared in 455.Bx 4.2 . 456