Copyright (c) 2002 Artur Grabowski <art@openbsd.org>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.Dd $Mdocdate: November 23 2015 $ .Dt FALLOC 9 .Os .Sh NAME .Nm falloc , .Nm fdrelease , .Nm FREF , .Nm FRELE , .Nm fd_getfile , .Nm getsock , .Nm getvnode .Nd an overview of file descriptor handling .Sh SYNOPSIS n sys/file.h n sys/filedesc.h .Ft int .Fn falloc "struct proc *p" "int flags" "struct file **resultfp" "int *resultfd" .Ft int .Fn fdrelease "struct proc *p" "int fd" .Ft void .Fn FREF "struct file *fp" .Ft int .Fn FRELE "struct file *fp" "struct proc *p" .Ft struct file * .Fn fd_getfile "struct filedesc *fdp" "int fd" .Ft int .Fn getsock "struct proc *p" "int fd" "struct file **fpp" n sys/file.h n sys/filedesc.h n sys/vnode.h .Ft int .Fn getvnode "struct proc *p" "int fd" "struct file **fpp" .Sh DESCRIPTION These functions provide the interface for the UNIX file descriptors. File descriptors can be used to access vnodes (see .Xr vnode 9 ) , sockets (see .Xr socket 2 ) , pipes (see .Xr pipe 2 ) , kqueues (see .Xr kqueue 2 ) , and various special purpose communication endpoints.
p A new file and a file descriptor for it are allocated with the function .Fn falloc . The .Fa flags argument can be used to set the .Dv UF_EXCLOSE flag on the new descriptor. The larval file and fd are returned via .Fa resultfp and .Fa resultfd , which must not be .Dv NULL . .Fn falloc initializes the new file to have a reference count of two: one for the reference from the file descriptor table and one for the caller to release with .Fn FRELE when it done initializing it.
p
A file descriptor is freed with
.Fn fdrelease .
This releases the reference that it holds to the underlying file;
if that's the last reference then the file will be freed.
with
.Xr closef 9 .
p The files are extracted from the file descriptor table using the functions .Fn fd_getfile .Fn fd_getfile performs all necessary checks to see if the file descriptor number is within the range of file descriptor table, and if the descriptor is valid.
p The files are extracted from the process context using the function .Fn getsock and .Fn getvnode . These functions are special cases that besides doing .Fn fd_getfile also check if the descriptor is a socket or a vnode respectively, return the proper errno on error and increase the use count with .Fn FREF . .Sh CONCURRENT ACCESS Since multiple processes can share the same file descriptor table, it's important that the file is not freed in one process while some other process is still accessing it. To solve that problem a special use count is kept with the functions .Fn FREF and .Fn FRELE . In most cases .Fn FREF should be used on a file after it has been extracted from the file descriptor table and .Fn FRELE should be called when the file won't be used anymore. There are cases when this isn't necessary, but since .Fn FREF and .Fn FRELE are cheap to use, there is no reason to risk introducing bugs by not using them. .Sh CODE REFERENCES The majority of those functions are implemented in
a sys/kern/kern_descrip.c . The function prototypes and the macros are located in
a sys/sys/filedesc.h . .Sh SEE ALSO .Xr vnode 9