NAME    [Toc]    [Back]

     file - an overview of file descriptor handling

SYNOPSIS    [Toc]    [Back]

     #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);

     void
     FRELE(struct file *fp);

     struct file *
     fd_getfile(struct filedesc *fdp, int fd);

     int
     getvnode(struct filedesc *fdp, int fd, struct file **fpp);

     int
     getsock(struct filedesc *fdp, int fd, struct file **fpp);

DESCRIPTION    [Toc]    [Back]

     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(), getvnode() and getsock().   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.
getsock() and
     getvnode() are special cases that besides doing fd_getfile()
also check
     if the descriptor is a vnode or socket,  return  the  proper
errno on error
     and increase the use count with FREF().

CONCURRENT ACCESS    [Toc]    [Back]

     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.

SEE ALSO    [Toc]    [Back]

     vnode(9)

CODE REFERENCES    [Toc]    [Back]

     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.

OpenBSD     3.6                         August      23,      2002