NetBSD/share/man/man9/file.9

.\"     $NetBSD: file.9,v 1.6 2003/04/16 13:35:28 wiz Exp $
.\"
.\" Copyright (c) 2002 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" 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 October 12, 2002
.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 proc *p"
.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 proc *p"
.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:
.Pp
.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 */
        struct ucred    *f_cred;        /* associated creds */
        struct fileops {
                int (*fo_read)(struct file *fp, off_t *offset,
			struct uio *uio, struct ucred *cred, int flags);
                int (*fo_write)(struct file *fp, off_t *offset,
                        struct uio *uio, struct ucred *cred, int flags);
                int (*fo_ioctl)(struct file *fp, u_long com, caddr_t data,
			struct proc *p);
                int (*fo_fcntl)(struct file *fp, u_int com, caddr_t data,
			struct proc *p);
                int (*fo_poll)(struct file *fp, int events,
			struct proc *p);
                int (*fo_stat)(struct file *fp, struct stat *sp,
			struct proc *p);
                int (*fo_close)(struct file *fp, struct proc *p);
        } *f_ops;
        off_t           f_offset;
        caddr_t         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 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 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" "p"
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 process
.Fa p ,
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 useable by ensuring that neither the
FIF_WANTCLOSE and FIF_LARVAL flags are not set in
.Em f_iflags .
.It Fn FILE_USE "fp"
Increment the reference count on file entry
.Fa fp .
.It Fn FILE_UNUSE "fp" "p"
Decrement the reference count on file entry
.Fa fp .
If the 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 FIF_LARVAL flag in
.Em f_iflags .
.El
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or using file entries
can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
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