1.\" $OpenBSD: file.9,v 1.22 2020/01/03 05:37:00 visa Exp $ 2.\" 3.\" Copyright (c) 2002 Artur Grabowski <art@openbsd.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. The name of the author may not be used to endorse or promote products 12.\" derived from this software without specific prior written permission 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.Dd $Mdocdate: January 3 2020 $ 26.Dt FALLOC 9 27.Os 28.Sh NAME 29.Nm falloc , 30.Nm fdrelease , 31.Nm FREF , 32.Nm FRELE , 33.Nm fd_getfile , 34.Nm fd_getfile_mode , 35.Nm fd_checkclosed , 36.Nm getsock , 37.Nm getvnode 38.Nd an overview of file descriptor handling 39.Sh SYNOPSIS 40.In sys/file.h 41.In sys/filedesc.h 42.Ft int 43.Fn falloc "struct proc *p" "int flags" "struct file **resultfp" "int *resultfd" 44.Ft int 45.Fn fdrelease "struct proc *p" "int fd" 46.Ft void 47.Fn FREF "struct file *fp" 48.Ft int 49.Fn FRELE "struct file *fp" "struct proc *p" 50.Ft struct file * 51.Fn fd_getfile "struct filedesc *fdp" "int fd" 52.Ft struct file * 53.Fn fd_getfile_mode "struct filedesc *fdp" "int fd" "int mode" 54.Ft int 55.Fn fd_checkclosed "struct filedesc *fdp" "int fd" "struct file *fp" 56.Ft int 57.Fn getsock "struct proc *p" "int fd" "struct file **fpp" 58.In sys/file.h 59.In sys/filedesc.h 60.In sys/vnode.h 61.Ft int 62.Fn getvnode "struct proc *p" "int fd" "struct file **fpp" 63.Sh DESCRIPTION 64These functions provide the interface for the UNIX file descriptors. 65File descriptors can be used to access vnodes (see 66.Xr vnode 9 ) , 67sockets (see 68.Xr socket 2 ) , 69pipes (see 70.Xr pipe 2 ) , 71kqueues (see 72.Xr kqueue 2 ) , 73and various special purpose communication endpoints. 74.Pp 75A new file and a file descriptor for it are allocated with the function 76.Fn falloc . 77The 78.Fa flags 79argument can be used to set the 80.Dv UF_EXCLOSE 81flag on the new descriptor. 82The larval file and fd are returned via 83.Fa resultfp 84and 85.Fa resultfd , 86which must not be 87.Dv NULL . 88.Fn falloc 89initializes the new file to have a reference count of two: 90one for the reference from the file descriptor table and one 91for the caller to release with 92.Fn FRELE 93when it's done initializing it. 94.Pp 95A file descriptor is freed with 96.Fn fdrelease . 97This releases the reference that it holds to the underlying file; 98if that's the last reference then the file will be freed. 99.\" with 100.\" .Xr closef 9 . 101The file descriptor table has to be locked on entry. 102.Fn fdrelease 103unlocks the table on return. 104.Pp 105The files are extracted from the file descriptor table using the 106function 107.Fn fd_getfile . 108.Fn fd_getfile 109performs all necessary checks to see if the file descriptor number is 110within the range of file descriptor table, and if the descriptor is 111valid. 112It also increases the descriptor's use count with 113.Fn FREF . 114.Pp 115.Fn fd_getfile_mode 116is like 117.Fn fd_getfile 118but also checks if the file has been opened with the given mode. 119.Pp 120.Fn fd_checkclosed 121checks if file descriptor 122.Fa fd 123has been closed and no longer points to file 124.Fa fp . 125The file must have been retrieved from the descriptor previously. 126.Pp 127The files are extracted from the process context using the 128function 129.Fn getsock 130and 131.Fn getvnode . 132These functions are special cases that besides doing 133.Fn fd_getfile 134also check if the descriptor is a socket or a vnode respectively, 135and return the proper errno on error. 136.Sh CONCURRENT ACCESS 137Since multiple processes can share the same file descriptor table, 138it's important that the file is not freed in one process while some 139other process is still accessing it. 140To solve that problem a special use count is kept with the functions 141.Fn FREF 142and 143.Fn FRELE . 144The function 145.Fn FREF 146increases the use count of a file descriptor. 147The function 148.Fn FRELE 149decreases the use count, and releases the file descriptor if the use count 150becomes zero. 151.Sh CODE REFERENCES 152The majority of those functions are implemented in 153.Pa sys/kern/kern_descrip.c . 154The function prototypes and the macros are located in 155.Pa sys/sys/file.h 156and 157.Pa sys/sys/filedesc.h . 158.Sh SEE ALSO 159.Xr vnode 9 160