NAME
filedesc,
dupfdopen,
falloc,
fd_getfile,
fdalloc,
fdcheckstd,
fdclear,
fdclone,
fdcloseexec,
fdcopy,
fdexpand,
fdfree,
fdinit,
fdrelease,
fdremove,
fdshare,
fdunshare —
file descriptor tables
and operations
SYNOPSIS
#include <sys/file.h>
#include <sys/filedesc.h>
int
falloc(
struct lwp
*l,
struct file
**resultfp,
int
*resultfd);
struct file *
fd_getfile(
struct
filedesc *fdp,
int
fd);
int
dupfdopen(
struct
lwp *l,
int indx,
int dfd,
int mode,
int error);
int
fdalloc(
struct
proc *p,
int want,
int *result);
int
fdcheckstd(
struct
lwp *l);
void
fdclear(
struct
lwp *l);
int
fdclone(
struct
lwp *l,
struct file
*fp,
int fd,
int flag,
const struct fileops *fops,
void *data);
void
fdcloseexec(
struct
lwp *l);
struct filedesc *
fdcopy(
struct
proc *p);
void
fdexpand(
struct
proc *p);
void
fdfree(
struct lwp
*l);
struct filedesc *
fdinit(
struct
proc *p);
int
fdrelease(
struct
lwp *l,
int fd);
void
fdremove(
struct
filedesc *fdp,
int
fd);
void
fdshare(
struct
proc *p1,
struct proc
*p2);
void
fdunshare(
struct
lwp *l);
DESCRIPTION
For user processes, all I/O is done through file descriptors. These file
descriptors represent underlying objects supported by the kernel and are
created by system calls specific to the type of object. In
NetBSD, six types of objects can be represented by
file descriptors: data files, pipes, sockets, event queues, crypto, and
miscellaneous.
The kernel maintains a descriptor table for each process which is used to
translate the external representation of a file descriptor into an internal
representation. The file descriptor is merely an index into this table. The
file descriptor table maintains the following information:
- the number of descriptors
allocated in the file descriptor table;
- approximate next free
descriptor;
- a reference count on the
file descriptor table; and
- an array of open file
entries.
On creation of the file descriptor table, a fixed number of file entries are
created. It is the responsibility of the file descriptor operations to expand
the available number of entries if more are required. Each file entry in the
descriptor table contains the information necessary to access the underlying
object and to maintain common information. See
file(9) for details of operations
on the file entries.
New file descriptors are generally allocated by
falloc() and
freed by
fdrelease(). File entries are extracted from the
file descriptor table by
fd_getfile(). Most of the remaining
functions in the interface are purpose specific and perform lower-level file
descriptor operations.
FUNCTIONS
The following functions are high-level interface routines to access the file
descriptor table for a process and its file entries.
-
-
- falloc(p,
*resultfp, *resultfd)
- Create a new open file entry and allocate a file descriptor
for process p. This operation is performed by
invoking fdalloc() to allocate the new file descriptor.
The credential on the file entry are inherited from process
p. The falloc() function is
responsible for expanding the file descriptor table when necessary.
A pointer to the file entry is returned in *resultfp
and the file descriptor is returned in *resultfd.
The falloc() function returns zero on success, otherwise
an appropriate error is returned.
-
-
- fd_getfile(fdp,
fd)
- Get the file entry for file descriptor
fd in the file descriptor table
fdp. The file entry is returned if it is valid and
useable, otherwise
NULL
is returned.
-
-
- dupfdopen(l,
indx, dfd,
mode, error)
- Duplicate file descriptor dfd for lwp
l.
The following functions operate on the file descriptor table for a process.
-
-
- fdalloc(p,
want, *result)
- Allocate a file descriptor want for
process p. The resultant file descriptor is returned
in *result. The fdalloc() function
returns zero on success, otherwise an appropriate error is returned.
-
-
- fdcheckstd(l)
- Check the standard file descriptors 0, 1, and 2 and ensure
they are referencing valid file descriptors. If they are not, create
references to /dev/null. This operation is necessary as
these file descriptors are given implicit significance in the Standard C
Library and it is unsafe for
setuid(2) and
setgid(2) processes to be
started with these file descriptors closed.
-
-
- fdclear(l)
- Clear the descriptor table for lwp l.
This operation is performed by invoking fdinit() to
initialise a new file descriptor table to replace the old file descriptor
table and invoking fdfree() to release the old one.
-
-
- fdclone(l,
fp, fd,
flag, fops,
data)
- This function is meant to be used by devices which allocate
a file entry upon open. fdclone() fills
fp with the given parameters. It always returns the
in-kernel errno value
EMOVEFD
, which is meant to
be returned from the device open routine. This special return value is
interpreted by the caller of the device open routine.
-
-
- fdcloseexec(l)
- Close any files for process p that
are marked “close on exec”. This operation is performed by
invoking fdunshare() for the process and invoking
fdrelease() on the appropriate file descriptor.
-
-
- fdcopy(p)
- Copy the file descriptor table from process
p and return a pointer to the copy. The returned
file descriptor is guaranteed to have a reference count of one. All file
descriptor state is maintained. The reference counts on each file entry
referenced by the file descriptor table is incremented accordingly.
-
-
- fdexpand(p)
- Expand the file descriptor table for process
p by allocating memory for additional file
descriptors.
-
-
- fdfree(l)
- Decrement the reference count on the file descriptor table
for lwp l and release the file descriptor table if
the reference count drops to zero.
-
-
- fdinit(p)
- Create a file descriptor table using the same current and
root directories of process p. The returned file
descriptor table is guaranteed to have a reference count of one.
-
-
- fdrelease(l,
fd)
- Remove file descriptor fd from the
file descriptor table of lwp l. The operation is
performed by invoking closef().
-
-
- fdremove(fdp,
fd)
- Unconditionally remove the file descriptor
fd from file descriptor table
fdp.
-
-
- fdshare(p1,
p2)
- Share the file descriptor table belonging to process
p1 with process p2. Process
p2 is assumed not to have a file descriptor table
already allocated. The reference count on the file descriptor table is
incremented. This function is used by
fork1(9).
-
-
- fdunshare(l)
- Ensure that lwp l does not share its
file descriptor table. If its file descriptor table has more than one
reference, the file descriptor table is copied by invoking
fdcopy(). The reference count on the original file
descriptor table is decremented.
RETURN VALUES
Successful operations return zero. A failed operation will return a non-zero
return value. Possible values include:
-
-
- [
EBADF
]
- Bad file descriptor specified.
-
-
- [
EMFILE
]
- Cannot exceed file descriptor limit.
-
-
- [
ENOSPC
]
- No space left in file descriptor table.
CODE REFERENCES
The framework for file descriptor handling is implemented within the file
sys/kern/kern_descrip.c.
SEE ALSO
file(9)