NAME
falloc, fdrelease,
FREF, FRELE,
fd_getfile, getsock,
getvnode —
an overview of file descriptor
handling
SYNOPSIS
#include
<sys/file.h>
#include <sys/filedesc.h>
int
falloc(struct
proc *p, struct file
**resultfp, int
*resultfd);
int
fdrelease(struct
proc *p, int
fd);
void
FREF(struct
file *fp);
int
FRELE(struct
file *fp, struct proc
*p);
struct file *
fd_getfile(struct
filedesc *fdp, int
fd);
int
getsock(struct
proc *p, int fd,
struct file **fpp);
#include
<sys/file.h>
#include <sys/filedesc.h>
#include <sys/vnode.h>
int
getvnode(struct
proc *p, int fd,
struct file **fpp);
DESCRIPTION
These functions provide the interface for the UNIX file descriptors. File descriptors can be used to access vnodes (see vnode(9)), sockets (see socket(2)), pipes (see pipe(2)), kqueues (see kqueue(2)), and various special purpose communication endpoints.
A new file descriptor is allocated with the function
falloc() and
freed with
fdrelease().
falloc() and fdrelease()
deal with allocating and freeing slots in the file descriptor table,
expanding the table when necessary and initializing the descriptor. It's
possible to do those things in smaller steps, but it's not recommended to
make complicated kernel APIs that require it.
The files are extracted from the file descriptor
table using the functions
fd_getfile()
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.
The files are extracted from the process context
using the function
getsock()
and
getvnode().
These functions are special cases that besides doing
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
FREF().
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 FREF() and
FRELE().
In most cases FREF() should be used on a file after
it has been extracted from the file descriptor table and
FRELE() should be called when the file won't be used
anymore. There are cases when this isn't necessary, but since
FREF() and FRELE() are cheap
to use, there is no reason to risk introducing bugs by not using them.
CODE REFERENCES
The majority of those functions are implemented in sys/kern/kern_descrip.c. The function prototypes and the macros are located in sys/sys/file.h and sys/sys/filedesc.h.