1.\" $OpenBSD: file.9,v 1.5 2003/04/15 04:14:29 jmc 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 August 23, 2002 26.Dt FILE 9 27.Os 28.Sh NAME 29.Nm vnode 30.Nd an overview of file descriptor handling 31.Sh SYNOPSIS 32.Fd #include <sys/file.h> 33.Fd #include <sys/filedesc.h> 34.Ft int 35.Fn falloc "struct proc *p" "struct file **fesultfp" "int *resultfd" 36.Ft int 37.Fn fdrelease "struct proc *p" "int fd" 38.Ft void 39.Fn FREF "struct file *fp" 40.Ft void 41.Fn FRELE "struct file *fp" 42.Ft struct file * 43.Fn fd_getfile "struct filedesc *fdp" "int fd" 44.Ft int 45.Fn getvnode "struct filedesc *fdp" "int fd" "struct file **fpp" 46.Ft int 47.Fn getsock "struct filedesc *fdp" "int fd" "struct file **fpp" 48.Sh DESCRIPTION 49These functions provide the interface for the UNIX file descriptors. 50File descriptors can be used to access vnodes (see 51.Xr vnode 9 ) , 52sockets (see 53.Xr socket 2 ) , 54pipes (see 55.Xr pipe 2 ) , 56kqueues (see 57.Xr kqueue 2 ) , 58and various special purpose communication endpoints. 59.Pp 60A new file descriptor is allocated with the function 61.Fn falloc 62and freed with 63.Fn fdrelease . 64.Fn falloc 65and 66.Fn fdrelease 67deal with allocating and freeing slots in the file descriptor table, 68expanding the table when necessary and initializing the descriptor. 69It's possible to do those things in smaller steps, but it's not 70recommended to make complicated kernel APIs that require it. 71.Pp 72The files are extracted from the file descriptor table using the 73functions 74.Fn fd_getfile , 75.Fn getvnode 76and 77.Fn getsock . 78.Fn fd_getfile 79performs all necessary checks to see if the file descriptor number is 80within the range of file descriptor table, and if the descriptor is 81valid. 82.Fn getsock 83and 84.Fn getvnode 85are special cases that besides doing 86.Fn fd_getfile 87also check if the descriptor is a vnode or socket, return the proper 88errno on error and increase the use count with 89.Fn FREF . 90.Sh CONCURRENT ACCESS 91Since multiple processes can share the same file descriptor table, 92it's important that the file is not freed in one process while some 93other process is still accessing it. 94To solve that problem a special use count is kept with the functions 95.Fn FREF 96and 97.Fn FRELE . 98In most cases 99.Fn FREF 100should be used on a file after it has been extracted 101from the file descriptor table and 102.Fn FRELE 103should be called when the file won't be used anymore. 104There are cases when this isn't necessary, but since 105.Fn FREF 106and 107.Fn FRELE 108are cheap to use, there is no reason to risk introducing bugs by 109not using them. 110.Sh SEE ALSO 111.Xr vnode 9 112.Sh CODE REFERENCES 113The majority of those functions are implemented in 114.Pa sys/kern/kern_descrip.c . 115The function prototypes and the macros are located in 116.Pa sys/sys/file.h 117and 118.Pa sys/sys/filedesc.h . 119