1.\" Copyright (c) 1983 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)fcntl.2 6.7 (Berkeley) 03/10/91 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 <sys/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 F_GETOWNX 103.It Dv O_NDELAY 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 EWOULDBLOCK . 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.Sh RETURN VALUES 125Upon successful completion, the value returned depends on 126.Fa cmd 127as follows: 128.Bl -tag -width F_GETOWNX -offset indent 129.It Dv F_DUPFD 130A new file descriptor. 131.It Dv F_GETFD 132Value of flag (only the low-order bit is defined). 133.It Dv F_GETFL 134Value of flags. 135.It Dv F_GETOWN 136Value of file descriptor owner. 137.It other 138Value other than -1. 139.El 140.Pp 141Otherwise, a value of -1 is returned and 142.Va errno 143is set to indicate the error. 144.Sh ERRORS 145.Fn Fcntl 146will fail if: 147.Bl -tag -width Er 148.It Bq Er EBADF 149.Fa Fildes 150is not a valid open file descriptor. 151.It Bq Er EMFILE 152.Fa Cmd 153is 154.Dv F_DUPFD 155and the maximum allowed number of file descriptors are currently 156open. 157.It Bq Er EINVAL 158.Fa Cmd 159is 160.Dv F_DUPFD 161and 162.Fa arg 163is negative or greater than the maximum allowable number 164(see 165.Xr getdtablesize 2 ) . 166.It Bq Er ESRCH 167.Fa Cmd 168is 169.Dv F_SETOWN 170and 171the process ID given as argument is not in use. 172.El 173.Sh SEE ALSO 174.Xr close 2 , 175.Xr execve 2 , 176.Xr getdtablesize 2 , 177.Xr open 2 , 178.Xr sigvec 2 179.Sh BUGS 180The asynchronous I/O facilities of 181.Dv FNDELAY 182and 183.Dv FASYNC 184are currently available only for tty and socket operations. 185.Sh HISTORY 186The 187.Nm 188function call appeared in 189.Bx 4.2 . 190