1.\" $OpenBSD: file.9,v 1.23 2024/11/09 15:54:14 matthieu 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: November 9 2024 $ 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" "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 larval file and fd are returned via 78.Fa resultfp 79and 80.Fa resultfd , 81which must not be 82.Dv NULL . 83.Fn falloc 84initializes the new file to have a reference count of two: 85one for the reference from the file descriptor table and one 86for the caller to release with 87.Fn FRELE 88when it's done initializing it. 89.Pp 90A file descriptor is freed with 91.Fn fdrelease . 92This releases the reference that it holds to the underlying file; 93if that's the last reference then the file will be freed. 94.\" with 95.\" .Xr closef 9 . 96The file descriptor table has to be locked on entry. 97.Fn fdrelease 98unlocks the table on return. 99.Pp 100The files are extracted from the file descriptor table using the 101function 102.Fn fd_getfile . 103.Fn fd_getfile 104performs all necessary checks to see if the file descriptor number is 105within the range of file descriptor table, and if the descriptor is 106valid. 107It also increases the descriptor's use count with 108.Fn FREF . 109.Pp 110.Fn fd_getfile_mode 111is like 112.Fn fd_getfile 113but also checks if the file has been opened with the given mode. 114.Pp 115.Fn fd_checkclosed 116checks if file descriptor 117.Fa fd 118has been closed and no longer points to file 119.Fa fp . 120The file must have been retrieved from the descriptor previously. 121.Pp 122The files are extracted from the process context using the 123function 124.Fn getsock 125and 126.Fn getvnode . 127These functions are special cases that besides doing 128.Fn fd_getfile 129also check if the descriptor is a socket or a vnode respectively, 130and return the proper errno on error. 131.Sh CONCURRENT ACCESS 132Since multiple processes can share the same file descriptor table, 133it's important that the file is not freed in one process while some 134other process is still accessing it. 135To solve that problem a special use count is kept with the functions 136.Fn FREF 137and 138.Fn FRELE . 139The function 140.Fn FREF 141increases the use count of a file descriptor. 142The function 143.Fn FRELE 144decreases the use count, and releases the file descriptor if the use count 145becomes zero. 146.Sh CODE REFERENCES 147The majority of those functions are implemented in 148.Pa sys/kern/kern_descrip.c . 149The function prototypes and the macros are located in 150.Pa sys/sys/file.h 151and 152.Pa sys/sys/filedesc.h . 153.Sh SEE ALSO 154.Xr vnode 9 155