257 lines
8.2 KiB
Groff
257 lines
8.2 KiB
Groff
.\" $NetBSD: file.9,v 1.19 2017/04/23 11:37:29 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002, 2005, 2006 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Gregory McGarry.
|
|
.\"
|
|
.\" 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. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``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 FOUNDATION OR CONTRIBUTORS
|
|
.\" 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 May 17, 2009
|
|
.Dt FILE 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm file ,
|
|
.Nm closef ,
|
|
.Nm ffree ,
|
|
.Nm FILE_IS_USABLE ,
|
|
.Nm FILE_USE ,
|
|
.Nm FILE_UNUSE ,
|
|
.Nm FILE_SET_MATURE
|
|
.Nd operations on file entries
|
|
.Sh SYNOPSIS
|
|
.In sys/file.h
|
|
.Ft int
|
|
.Fn closef "struct file *fp" "struct lwp *l"
|
|
.Ft void
|
|
.Fn ffree "struct file *fp"
|
|
.Ft int
|
|
.Fn FILE_IS_USABLE "struct file *fp"
|
|
.Ft void
|
|
.Fn FILE_USE "struct file *fp"
|
|
.Ft void
|
|
.Fn FILE_UNUSE "struct file *fp" "struct lwp *l"
|
|
.Ft void
|
|
.Fn FILE_SET_MATURE "struct file *fp"
|
|
.Sh DESCRIPTION
|
|
The file descriptor table of a process references a file entry for
|
|
each file used by the kernel.
|
|
See
|
|
.Xr filedesc 9
|
|
for details of the file descriptor table.
|
|
Each file entry is given by:
|
|
.Bd -literal
|
|
struct file {
|
|
LIST_ENTRY(file) f_list; /* list of active files */
|
|
int f_flag;
|
|
int f_iflags; /* internal flags */
|
|
int f_type; /* descriptor type */
|
|
u_int f_count; /* reference count */
|
|
u_int f_msgcount; /* message queue references */
|
|
int f_usecount; /* number active users */
|
|
kauth_cred_t f_cred; /* creds associated with descriptor */
|
|
struct fileops {
|
|
int (*fo_read)(struct file *fp, off_t *offset,
|
|
struct uio *uio, kauth_cred_t cred, int flags);
|
|
int (*fo_write)(struct file *fp, off_t *offset,
|
|
struct uio *uio, kauth_cred_t cred, int flags);
|
|
int (*fo_ioctl)(struct file *fp, u_long com, void *data,
|
|
struct lwp *l);
|
|
int (*fo_fcntl)(struct file *fp, u_int com, void *data,
|
|
struct lwp *l);
|
|
int (*fo_poll)(struct file *fp, int events,
|
|
struct lwp *l);
|
|
int (*fo_stat)(struct file *fp, struct stat *sp,
|
|
struct lwp *l);
|
|
int (*fo_close)(struct file *fp, struct lwp *l);
|
|
} *f_ops;
|
|
off_t f_offset;
|
|
void *f_data; /* descriptor data */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Nx
|
|
treats file entries in an object-oriented fashion after they are created.
|
|
Each entry specifies the object type,
|
|
.Em f_type ,
|
|
which can have the values
|
|
.Dv DTYPE_VNODE ,
|
|
.Dv DTYPE_SOCKET ,
|
|
.Dv DTYPE_PIPE
|
|
and
|
|
.Dv DTYPE_MISC .
|
|
The file entry also has a pointer to a data structure,
|
|
.Em f_data ,
|
|
that contains information specific to the instance of the underlying object.
|
|
The data structure is opaque to the routines that manipulate the file entry.
|
|
Each entry also contains an array of function pointers,
|
|
.Em f_ops ,
|
|
that translate the generic operations on a file descriptor into the
|
|
specific action associated with its type.
|
|
A reference to the data structure is passed as the first parameter to a
|
|
function that implements a file operation.
|
|
The operations that must be implemented for each descriptor type are
|
|
read, write, ioctl, fcntl, poll, stat, and close.
|
|
See
|
|
.Xr vnfileops 9
|
|
for an overview of the vnode file operations.
|
|
All state associated with an instance of an object must be stored in
|
|
that instance's data structure; the underlying objects are not permitted
|
|
to manipulate the file entry themselves.
|
|
.Pp
|
|
For data files, the file entry points to a
|
|
.Xr vnode 9
|
|
structure.
|
|
Pipes and sockets do not have data blocks allocated on the disk and
|
|
are handled by the special-device filesystem that calls appropriate
|
|
drivers to handle I/O for them.
|
|
For pipes, the file entry points to a system block that is used during
|
|
data transfer.
|
|
For sockets, the file entry points to a system block that is used in
|
|
doing interprocess communications.
|
|
.Pp
|
|
The descriptor table of a process (and thus access to the objects to
|
|
which the descriptors refer) is inherited from its parent, so several
|
|
different processes may reference the same file entry.
|
|
Thus, each file entry has a reference count,
|
|
.Em f_count .
|
|
Each time a new reference is created, the reference count is incremented.
|
|
When a descriptor is closed, the reference count is decremented.
|
|
When the reference count drops to zero, the file entry is freed.
|
|
.Pp
|
|
Some file descriptor semantics can be altered through the
|
|
.Ar flags
|
|
argument to the
|
|
.Xr open 2
|
|
system call.
|
|
These flags are recorded in
|
|
.Em f_flags
|
|
member of the file entry.
|
|
For example, the flags record whether the descriptor is open for
|
|
reading, writing, or both reading and writing.
|
|
The following flags and their corresponding
|
|
.Xr open 2
|
|
flags are:
|
|
.Pp
|
|
.Bl -tag -offset indent -width FNONBLOCK -compact
|
|
.It FAPPEND
|
|
.Dv O_APPEND
|
|
.It FASYNC
|
|
.Dv O_ASYNC
|
|
.It O_FSYNC
|
|
.Dv O_SYNC
|
|
.It FNDELAY
|
|
.Dv O_NONBLOCK
|
|
.It O_NDELAY
|
|
.Dv O_NONBLOCK
|
|
.It FNONBLOCK
|
|
.Dv O_NONBLOCK
|
|
.It FFSYNC
|
|
.Dv O_SYNC
|
|
.It FDSYNC
|
|
.Dv O_DSYNC
|
|
.It FRSYNC
|
|
.Dv O_RSYNC
|
|
.It FALTIO
|
|
.Dv O_ALT_IO
|
|
.El
|
|
.Pp
|
|
Some additional state-specific flags are recorded in the
|
|
.Em f_iflags
|
|
member.
|
|
Valid values include:
|
|
.Pp
|
|
.Bl -tag -offset indent -width FIF_WANTCLOSE -compact
|
|
.It Dv FIF_WANTCLOSE
|
|
If set, then the reference count on the file is zero, but there were
|
|
multiple users of the file.
|
|
This can happen if a file descriptor table is shared by multiple processes.
|
|
This flag notifies potential users that the file is closing and will
|
|
prevent them from adding additional uses to the file.
|
|
.It Dv FIF_LARVAL
|
|
The file entry is not fully constructed (mature) and should not be used.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2
|
|
system calls do not take an offset in the file as an argument.
|
|
Instead, each read or write updates the current file offset,
|
|
.Em f_offset
|
|
in the file according to the number of bytes transferred.
|
|
Since more than one process may open the same file and each needs its
|
|
own offset in the file, the offset cannot be stored in the per-object
|
|
data structure.
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width compact
|
|
.It Fn closef "fp" "l"
|
|
The internal form of
|
|
.Xr close 2
|
|
which decrements the reference count on file entry
|
|
.Fa fp .
|
|
The
|
|
.Fn closef
|
|
function release all locks on the file owned by lwp
|
|
.Fa l ,
|
|
decrements the reference count on the file entry, and invokes
|
|
.Fn ffree
|
|
to free the file entry.
|
|
.It Fn ffree "struct file *fp"
|
|
Free file entry
|
|
.Fa fp .
|
|
The file entry was created in
|
|
.Xr falloc 9 .
|
|
.It Fn FILE_IS_USABLE "fp"
|
|
Ensure that the file entry is usable by ensuring that neither the
|
|
.Dv FIF_WANTCLOSE
|
|
flag nor the
|
|
.Dv FIF_LARVAL
|
|
flag is set in
|
|
.Em f_iflags .
|
|
.It Fn FILE_USE "fp"
|
|
Increment the reference count on file entry
|
|
.Fa fp .
|
|
.It Fn FILE_UNUSE "fp" "l"
|
|
Decrement the reference count on file entry
|
|
.Fa fp .
|
|
If the
|
|
.Dv FIF_WANTCLOSE
|
|
flag is set in
|
|
.Em f_iflags ,
|
|
the file entry is freed.
|
|
.It Fn FILE_SET_MATURE "fp"
|
|
Mark the file entry as being fully constructed (mature) by clearing the
|
|
.Dv FIF_LARVAL
|
|
flag in
|
|
.Em f_iflags .
|
|
.El
|
|
.Sh CODE REFERENCES
|
|
The framework for file entry handling is implemented within the file
|
|
.Pa sys/kern/kern_descrip.c .
|
|
.Sh SEE ALSO
|
|
.Xr dofileread 9 ,
|
|
.Xr filedesc 9 ,
|
|
.Xr vnfileops 9 ,
|
|
.Xr vnode 9
|