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.1 (Berkeley) 07/11/93 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.Bd -literal 128struct flock { 129 off_t l_start; /* starting offset */ 130 off_t l_len; /* len = 0 means until end of file */ 131 pid_t l_pid; /* lock owner */ 132 short l_type; /* lock type: read/write, etc. */ 133 short l_whence; /* type of l_start */ 134}; 135.Ed 136The commands available for advisory record locking are as follows: 137.Bl -tag -width F_SETLKWX 138.It Dv F_GETLK 139Get the first lock that blocks the lock description pointed to by the 140third argument, 141.Fa arg , 142taken as a pointer to a 143.Fa "struct flock" 144(see above). 145The information retrieved overwrites the information passed to 146.Nm fcntl 147in the 148.Fa flock 149structure. 150If no lock is found that would prevent this lock from being created, 151the structure is left unchanged by this function call except for the 152lock type which is set to 153.Dv F_UNLCK . 154.It Dv F_SETLK 155Set or clear a file segment lock according to the lock description 156pointed to by the third argument, 157.Fa arg , 158taken as a pointer to a 159.Fa "struct flock" 160(see above). 161.Dv F_SETLK 162is used to establish shared (or read) locks 163.Dv (F_RDLCK) 164or exclusive (or write) locks, 165.Dv (F_WRLCK) , 166as well as remove either type of lock 167.Dv (F_UNLCK) . 168If a shared or exclusive lock cannot be set, 169.Nm fcntl 170returns immediately with 171.Er EACCES . 172.It Dv F_SETLKW 173This command is the same as 174.Dv F_SETLK 175except that if a shared or exclusive lock is blocked by other locks, 176the process waits until the request can be satisfied. 177If a signal that is to be caught is received while 178.Nm fcntl 179is waiting for a region, the 180.Nm fcntl 181will be interrupted if the signal handler has not specified the 182.Dv SA_RESTART 183(see 184.Xr sigaction 2 ) . 185.El 186.Pp 187When a shared lock has been set on a segment of a file, 188other processes can set shared locks on that segment 189or a portion of it. 190A shared lock prevents any other process from setting an exclusive 191lock on any portion of the protected area. 192A request for a shared lock fails if the file descriptor was not 193opened with read access. 194.Pp 195An exclusive lock prevents any other process from setting a shared lock or 196an exclusive lock on any portion of the protected area. 197A request for an exclusive lock fails if the file was not 198opened with write access. 199.Pp 200The value of 201.Fa l_whence 202is 203.Dv SEEK_SET , 204.Dv SEEK_CUR , 205or 206.Dv SEEK_END 207to indicate that the relative offset, 208.Fa l_start 209bytes, will be measured from the start of the file, 210current position, or end of the file, respectively. 211The value of 212.Fa l_len 213is the number of consecutive bytes to be locked. 214If 215.Fa l_len 216is negative, the result is undefined. 217The 218.Fa l_pid 219field is only used with 220.Dv F_GETLK 221to return the process ID of the process holding a blocking lock. 222After a successful 223.Dv F_GETLK 224request, the value of 225.Fa l_whence 226is 227.Dv SEEK_SET . 228.Pp 229Locks may start and extend beyond the current end of a file, 230but may not start or extend before the beginning of the file. 231A lock is set to extend to the largest possible value of the 232file offset for that file if 233.Fa l_len 234is set to zero. If 235.Fa l_whence 236and 237.Fa l_start 238point to the beginning of the file, and 239.Fa l_len 240is zero, the entire file is locked. 241If an application wishes only to do entire file locking, the 242.Xr flock 2 243system call is much more efficient. 244.Pp 245There is at most one type of lock set for each byte in the file. 246Before a successful return from an 247.Dv F_SETLK 248or an 249.Dv F_SETLKW 250request when the calling process has previously existing locks 251on bytes in the region specified by the request, 252the previous lock type for each byte in the specified 253region is replaced by the new lock type. 254As specified above under the descriptions 255of shared locks and exclusive locks, an 256.Dv F_SETLK 257or an 258.Dv F_SETLKW 259request fails or blocks respectively when another process has existing 260locks on bytes in the specified region and the type of any of those 261locks conflicts with the type specified in the request. 262.Pp 263This interface follows the completely stupid semantics of System V and 264.St -p1003.1-88 265that require that all locks associated with a file for a given process are 266removed when \fIany\fP file descriptor for that file is closed by that process. 267This semantic means that applications must be aware of any files that 268a subroutine library may access. 269For example if an application for updating the password file locks the 270password file database while making the update, and then calls 271.Xr getpwname 3 272to retrieve a record, 273the lock will be lost because 274.Xr getpwname 3 275opens, reads, and closes the password database. 276The database close will release all locks that the process has 277associated with the database, even if the library routine never 278requested a lock on the database. 279Another minor semantic problem with this interface is that 280locks are not inherited by a child process created using the 281.Xr fork 2 282function. 283The 284.Xr flock 2 285interface has much more rational last close semantics and 286allows locks to be inherited by child processes. 287.Xr Flock 2 288is recommended for applications that want to ensure the integrity 289of their locks when using library routines or wish to pass locks 290to their children. 291Note that 292.Xr flock 2 293and 294.Xr fcntl 2 295locks may be safely used concurrently. 296.Pp 297All locks associated with a file for a given process are 298removed when the process terminates. 299.Pp 300A potential for deadlock occurs if a process controlling a locked region 301is put to sleep by attempting to lock the locked region of another process. 302This implementation detects that sleeping until a locked region is unlocked 303would cause a deadlock and fails with an 304.Er EDEADLK 305error. 306.Sh RETURN VALUES 307Upon successful completion, the value returned depends on 308.Fa cmd 309as follows: 310.Bl -tag -width F_GETOWNX -offset indent 311.It Dv F_DUPFD 312A new file descriptor. 313.It Dv F_GETFD 314Value of flag (only the low-order bit is defined). 315.It Dv F_GETFL 316Value of flags. 317.It Dv F_GETOWN 318Value of file descriptor owner. 319.It other 320Value other than -1. 321.El 322.Pp 323Otherwise, a value of -1 is returned and 324.Va errno 325is set to indicate the error. 326.Sh ERRORS 327.Fn Fcntl 328will fail if: 329.Bl -tag -width Er 330.It Bq Er EACCES 331The argument 332.Fa arg 333is 334.Dv F_SETLK , 335the type of lock 336.Fa (l_type) 337is a shared lock 338.Dv (F_RDLCK) 339or exclusive lock 340.Dv (F_WRLCK) , 341and the segment of a file to be locked is already 342exclusive-locked by another process; 343or the type is an exclusive lock and some portion of the 344segment of a file to be locked is already shared-locked or 345exclusive-locked by another process. 346.It Bq Er EBADF 347.Fa Fildes 348is not a valid open file descriptor. 349.Pp 350The argument 351.Fa cmd 352is 353.Dv F_SETLK 354or 355.Dv F_SETLKW , 356the type of lock 357.Fa (l_type) 358is a shared lock 359.Dv (F_RDLCK) , 360and 361.Fa fildes 362is not a valid file descriptor open for reading. 363.Pp 364The argument 365.Fa cmd 366is 367.Dv F_SETLK 368or 369.Dv F_SETLKW , 370the type of lock 371.Fa (l_type) 372is an exclusive lock 373.Dv (F_WRLCK) , 374and 375.Fa fildes 376is not a valid file descriptor open for writing. 377.It Bq Er EMFILE 378.Fa Cmd 379is 380.Dv F_DUPFD 381and the maximum allowed number of file descriptors are currently 382open. 383.It Bq Er EDEADLK 384The argument 385.Fa cmd 386is 387.Dv F_SETLKW , 388and a deadlock condition was detected. 389.It Bq Er EINTR 390The argument 391.Fa cmd 392is 393.Dv F_SETLKW , 394and the function was interrupted by a signal. 395.It Bq Er EINVAL 396.Fa Cmd 397is 398.Dv F_DUPFD 399and 400.Fa arg 401is negative or greater than the maximum allowable number 402(see 403.Xr getdtablesize 2 ) . 404.Pp 405The argument 406.Fa cmd 407is 408.Dv F_GETLK , 409.Dv F_SETLK , 410or 411.Dv F_SETLKW 412and the data to which 413.Fa arg 414points is not valid, or 415.Fa fildes 416refers to a file that does not support locking. 417.It Bq Er EMFILE 418The argument 419.Fa cmd 420is 421.Dv F_DUPED 422and the maximum number of file descriptors permitted for the 423process are already in use, 424or no file descriptors greater than or equal to 425.Fa arg 426are available. 427.It Bq Er ENOLCK 428The argument 429.Fa cmd 430is 431.Dv F_SETLK 432or 433.Dv F_SETLKW , 434and satisfying the lock or unlock request would result in the 435number of locked regions in the system exceeding a system-imposed limit. 436.It Bq Er ESRCH 437.Fa Cmd 438is 439.Dv F_SETOWN 440and 441the process ID given as argument is not in use. 442.El 443.Sh SEE ALSO 444.Xr close 2 , 445.Xr execve 2 , 446.Xr flock 2 , 447.Xr getdtablesize 2 , 448.Xr open 2 , 449.Xr sigvec 2 450.Sh HISTORY 451The 452.Nm 453function call appeared in 454.Bx 4.2 . 455