NAME
vnodeops,
VOP_LOOKUP,
VOP_CREATE,
VOP_MKNOD,
VOP_OPEN,
VOP_CLOSE,
VOP_ACCESS,
VOP_GETATTR,
VOP_SETATTR,
VOP_READ,
VOP_WRITE,
VOP_FALLOCATE,
VOP_FDISCARD,
VOP_IOCTL,
VOP_FCNTL,
VOP_POLL,
VOP_KQFILTER,
VOP_REVOKE,
VOP_MMAP,
VOP_FSYNC,
VOP_SEEK,
VOP_REMOVE,
VOP_LINK,
VOP_RENAME,
VOP_MKDIR,
VOP_RMDIR,
VOP_SYMLINK,
VOP_READDIR,
VOP_READLINK,
VOP_ABORTOP,
VOP_INACTIVE,
VOP_RECLAIM,
VOP_LOCK,
VOP_UNLOCK,
VOP_ISLOCKED,
VOP_BMAP,
VOP_PRINT,
VOP_PATHCONF,
VOP_ADVLOCK,
VOP_WHITEOUT,
VOP_GETPAGES,
VOP_PUTPAGES,
VOP_STRATEGY,
VOP_BWRITE,
VOP_GETEXTATTR,
VOP_SETEXTATTR,
VOP_LISTEXTATTR,
VOP_DELETEEXTATTR —
vnode operations
SYNOPSIS
#include <sys/param.h>
#include <sys/buf.h>
#include <sys/dirent.h>
#include <sys/vnode.h>
#include <sys/mount.h>
#include <sys/namei.h>
#include <sys/unistd.h>
#include <sys/fcntl.h>
#include <sys/lockf.h>
#include <sys/extattr.h>
int
VOP_LOOKUP(
struct
vnode *dvp,
struct vnode
**vpp,
struct componentname
*cnp);
int
VOP_CREATE(
struct
vnode *dvp,
struct vnode
**vpp,
struct componentname
*cnp,
struct vattr
*vap);
int
VOP_MKNOD(
struct
vnode *dvp,
struct vnode
**vpp,
struct componentname
*cnp,
struct vattr
*vap);
int
VOP_OPEN(
struct
vnode *vp,
int mode,
kauth_cred_t cred);
int
VOP_CLOSE(
struct
vnode *vp,
int fflag,
kauth_cred_t cred);
int
VOP_ACCESS(
struct
vnode *vp,
int mode,
kauth_cred_t cred);
int
VOP_GETATTR(
struct
vnode *vp,
struct vattr
*vap,
kauth_cred_t
cred);
int
VOP_SETATTR(
struct
vnode *vp,
struct vattr
*vap,
kauth_cred_t
cred);
int
VOP_READ(
struct
vnode *vp,
struct uio
*uio,
int ioflag,
kauth_cred_t cred);
int
VOP_WRITE(
struct
vnode *vp,
struct uio
*uio,
int ioflag,
kauth_cred_t cred);
int
VOP_FALLOCATE(
struct
vnode *vp,
off_t pos,
off_t len);
int
VOP_FDISCARD(
struct
vnode *vp,
off_t pos,
off_t len);
int
VOP_IOCTL(
struct
vnode *vp,
u_long
command,
void *data,
int fflag,
kauth_cred_t cred);
int
VOP_FCNTL(
struct
vnode *vp,
u_int
command,
void *data,
int fflag,
kauth_cred_t cred);
int
VOP_POLL(
struct
vnode *vp,
int
events);
int
VOP_KQFILTER(
struct
vnode *vp,
struct knote
*kn);
int
VOP_REVOKE(
struct
vnode *vp,
int
flags);
int
VOP_MMAP(
struct
vnode *vp,
vm_prot_t
prot,
kauth_cred_t
cred);
int
VOP_FSYNC(
struct
vnode *vp,
kauth_cred_t
cred,
int flags,
off_t offlo,
off_t offhi);
int
VOP_SEEK(
struct
vnode *vp,
off_t
oldoff,
off_t newoff,
kauth_cred_t cred);
int
VOP_REMOVE(
struct
vnode *dvp,
struct vnode
*vp,
struct componentname
*cnp);
int
VOP_LINK(
struct
vnode *dvp,
struct vnode
*vp,
struct componentname
*cnp);
int
VOP_RENAME(
struct
vnode *fdvp,
struct vnode
*fvp,
struct componentname
*fcnp,
struct vnode
*tdvp,
struct vnode
*tvp,
struct componentname
*tcnp);
int
VOP_MKDIR(
struct
vnode *dvp,
struct vnode
**vpp,
struct componentname
*cnp,
struct vattr
*vap);
int
VOP_RMDIR(
struct
vnode *dvp,
struct vnode
*vp,
struct componentname
*cnp);
int
VOP_SYMLINK(
struct
vnode *dvp,
struct vnode
**vpp,
struct componentname
*cnp,
struct vattr
*vap,
char *target);
int
VOP_READDIR(
struct
vnode *vp,
struct uio
*uio,
kauth_cred_t
cred,
int *eofflag,
off_t **cookies,
int *ncookies);
int
VOP_READLINK(
struct
vnode *vp,
struct uio
*uio,
kauth_cred_t
cred);
int
VOP_ABORTOP(
struct
vnode *dvp,
struct
componentname *cnp);
int
VOP_INACTIVE(
struct
vnode *vp);
int
VOP_RECLAIM(
struct
vnode *vp);
int
VOP_LOCK(
struct
vnode *vp,
int
flags);
int
VOP_UNLOCK(
struct
vnode *vp);
int
VOP_ISLOCKED(
struct
vnode *vp);
int
VOP_BMAP(
struct
vnode *vp,
daddr_t
bn,
struct vnode
**vpp,
daddr_t *bnp,
int *runp);
int
VOP_PRINT(
struct
vnode *vp);
int
VOP_PATHCONF(
struct
vnode *vp,
int name,
register_t *retval);
int
VOP_ADVLOCK(
struct
vnode *vp,
void *id,
int op,
struct flock *fl,
int flags);
int
VOP_WHITEOUT(
struct
vnode *dvp,
struct
componentname *cnp,
int
flags);
int
VOP_GETPAGES(
struct
vnode *vp,
voff_t
offset,
struct vm_page
**m,
int *count,
int centeridx,
vm_prot_t access_type,
int advice,
int flags);
int
VOP_PUTPAGES(
struct
vnode *vp,
voff_t
offlo,
voff_t offhi,
int flags);
int
VOP_STRATEGY(
struct
vnode *vp,
struct buf
*bp);
int
VOP_BWRITE(
struct
vnode *vp,
struct buf
*bp);
int
VOP_GETEXTATTR(
struct
vnode *vp,
int
attrnamespace,
const char
*name,
struct uio
*uio,
size_t *size,
kauth_cred_t cred);
int
VOP_SETEXTATTR(
struct
vnode *vp,
int
attrnamespace,
const char
*name,
struct uio
*uio,
kauth_cred_t
cred);
int
VOP_LISTEXTATTR(
struct
vnode *vp,
int
attrnamespace,
struct uio
*uio,
size_t *size,
kauth_cred_t cred);
int
VOP_DELETEEXTATTR(
struct
vnode *vp,
int
attrnamespace,
const char
*name,
kauth_cred_t
cred);
Not all header files are required for each function.
DESCRIPTION
The vnode operations vector describes what operations can be done to the file
associated with the vnode. The system maintains one vnode operations vector
for each file system type configured into the kernel. The vnode operations
vector contains a pointer to a function for each operation supported by the
file system. Many of the functions described in the vnode operations vector
are closely related to their corresponding system calls. In most cases, they
are called as a result of the system call associated with the operation being
invoked.
Functions in the vnode operations vector are invoked using specialized macros.
The following table gives a summary of the operations.
Macro |
Description |
VOP_LOOKUP |
Lookup file name in name
cache |
VOP_CREATE |
Create a new file |
VOP_MKNOD |
Make a new device |
VOP_OPEN |
Open a file |
VOP_CLOSE |
Close a file |
VOP_ACCESS |
Determine file
accessibility |
VOP_GETATTR |
Get file attributes |
VOP_SETATTR |
Set file attributes |
VOP_READ |
Read from a file |
VOP_WRITE |
Write to a file |
VOP_FALLOCATE |
Allocate backing for a
file |
VOP_FDISCARD |
Discard backing for a
file |
VOP_IOCTL |
Perform device-specific
I/O |
VOP_FCNTL |
Perform file control |
VOP_POLL |
Test if poll event has
occurred |
VOP_KQFILTER |
Register a knote |
VOP_REVOKE |
Eliminate vnode
activity |
VOP_MMAP |
Map file into user address
space |
VOP_FSYNC |
Flush pending data to
disk |
VOP_SEEK |
Test if file is
seekable |
VOP_REMOVE |
Remove a file |
VOP_LINK |
Link a file |
VOP_RENAME |
Rename a file |
VOP_MKDIR |
Make a new directory |
VOP_RMDIR |
Remove a directory |
VOP_SYMLINK |
Create a symbolic
link |
VOP_READDIR |
Read directory entry |
VOP_READLINK |
Read contents of a
symlink |
VOP_ABORTOP |
Abort pending
operation |
VOP_INACTIVE |
Release the inactive
vnode |
VOP_RECLAIM |
Reclaim vnode for another
file |
VOP_LOCK |
Sleep until vnode lock is
free |
VOP_UNLOCK |
Wake up process sleeping
on lock |
VOP_ISLOCKED |
Test if vnode is
locked |
VOP_BMAP |
Logical block number
conversion |
VOP_PRINT |
Print debugging
information |
VOP_PATHCONF |
Return POSIX pathconf
data |
VOP_ADVLOCK |
Advisory record
locking |
VOP_WHITEOUT |
Whiteout vnode |
VOP_GETPAGES |
Read VM pages from
file |
VOP_PUTPAGES |
Write VM pages to
file |
VOP_STRATEGY |
Read/write a file system
buffer |
VOP_BWRITE |
Write a file system
buffer |
VOP_GETEXTATTR |
Get extended
attribute |
VOP_SETEXTATTR |
Set extended
attribute |
VOP_LISTEXTATTR |
List extended
attributes |
VOP_DELETEEXTATTR |
Remove extended
attribute |
The implementation details of the vnode operations vector are not quite what is
described here.
If the file system type does not support a specific operation, it must
nevertheless assign an appropriate stub in the vnode operations vector to do
the minimum required of it. In most cases, such functions either do nothing or
return an error value to the effect that it is not supported.
Many of the functions in the vnode operations vector take a componentname
structure. It is used to encapsulate many parameters into a single function
argument. It has the following structure:
struct componentname {
/*
* Arguments to lookup.
*/
uint32_t cn_nameiop; /* namei operation */
uint32_t cn_flags; /* flags to namei */
kauth_cred_t cn_cred; /* credentials */
/*
* Shared between lookup and commit routines.
*/
const char *cn_nameptr; /* pointer to looked up name */
size_t cn_namelen; /* length of looked up component */
size_t cn_consume; /* chars to consume in lookup() */
};
The top half of the structure is used exclusively for the pathname lookups using
VOP_LOOKUP() and is initialized by the caller. The semantics
of the lookup are affected by the lookup operation specified in
cn_nameiop and the flags specified in
cn_flags. Valid operations are:
- LOOKUP
- perform name lookup only
- CREATE
- set up for file creation
- DELETE
- set up for file deletion
- RENAME
- set up for file renaming
- OPMASK
- mask for operation
Valid values for
cn->cn_flags are:
- LOCKLEAF
- lock inode on return
- LOCKPARENT
- want parent vnode returned locked
- NOCACHE
- name must not be left in name cache (see
namecache(9))
- FOLLOW
- follow symbolic links
- NOFOLLOW
- do not follow symbolic links (pseudo)
- MODMASK
- mask of operational modifiers
No vnode operations may be called from interrupt context. Most operations also
require the vnode to be locked on entry. To prevent deadlocks, when acquiring
locks on multiple vnodes, the lock of parent directory must be acquired before
the lock on the child directory.
Vnode operations for a file system type generally should not be called directly
from the kernel, but accessed indirectly through the high-level convenience
functions discussed in
vnsubr(9).
FUNCTIONS
-
-
- VOP_LOOKUP(dvp,
vpp, cnp)
- Lookup a single pathname component in a given directory.
The argument dvp is the locked vnode of the
directory to search and cnp is the pathname
component to be searched for. If the pathname component is found, the
address of the resulting unlocked vnode is returned in
vpp. The operation specified in
cnp->cn_nameiop indicates
VOP_LOOKUP() the reason for requesting the lookup and
uses it to cache file system type specific information in the vnode for
subsequent operations.
There are three types of lookups: ".", ".." (ISDOTDOT),
and regular. If the pathname component being searched for is
".", then dvp has an extra reference added
to it and it is returned in *vpp. For other pathname
components, VOP_LOOKUP() checks the accessibility of the
directory and searches the name cache for the pathname component. See
namecache(9). If the
pathname is not found in the name cache, the directory is searched for the
pathname. The resulting unlocked vnode is returned in
vpp. dvp is always returned
locked.
On failure *vpp is
NULL
, and
*dvp is left locked. If the operation is successful
*vpp is unlocked and zero is returned. Typically, if
*vpp and dvp are the same
vnode the caller will need to release twice (decrement the reference
count) and unlock once.
-
-
- VOP_CREATE(dvp,
vpp, cnp,
vap)
- Create a new file in a given directory. The argument
dvp is the locked vnode of the directory to create
the new file in and cnp is the pathname component of
the new file. The argument vap specifies the
attributes that the new file should be created with. If the file is
successfully created, the address of the resulting unlocked vnode is
returned in vpp and zero is returned.
This function is called after VOP_LOOKUP() when a file is
being created. Normally, VOP_LOOKUP() will have set the
SAVENAME flag in cnp->cn_flags to keep the memory
pointed to by cnp->cn_pnbuf valid. If an error is
detected when creating the file, this memory is released. If the file is
created successfully it will be released unless the SAVESTART flags in
specified in cnp->cn_flags.
-
-
- VOP_MKNOD(dvp,
vpp, cnp,
vap)
- Make a new device-special file in a given directory. The
argument dvp is the locked vnode of the directory to
create the new device-special file in and cnp is the
pathname component of the new device-special file. The argument
vap specifies the attributes that the new
device-special file should be created with. If the file is successfully
created, the address of the resulting unlocked vnode is returned in
vpp and zero is returned.
This function is called after VOP_LOOKUP() when a
device-special file is being created. Normally,
VOP_LOOKUP() will have set the SAVENAME flag in
cnp->cn_flags to keep the memory pointed to by
cnp->cn_pnbuf valid. If an error is detected when
creating the device-special file, this memory is released. If the
device-special file is created successfully it will be released unless the
SAVESTART flags in specified in cnp->cn_flags.
-
-
- VOP_OPEN(vp,
mode, cred)
- Open a file. The argument vp is the
vnode of the file to open and mode specifies the
access mode required by the calling process. The calling credentials are
specified by cred. The access mode is a set of
flags, including FREAD, FWRITE, O_NONBLOCK, O_APPEND, etc.
VOP_OPEN() must be called before a file can be accessed
by a thread. The vnode reference count is incremented.
VOP_OPEN() expects the vnode vp to
be locked on entry and will leave it locked on return. If the operation is
successful zero is returned, otherwise an appropriate error code is
returned.
-
-
- VOP_CLOSE(vp,
fflag, cred)
- Close a file. The argument vp is the
vnode of the file to close and fflag specifies the
access mode by the calling process. The possible flags are
FREAD
, FWRITE
and
FNONBLOCK
. The calling credentials are specified
by cred. VOP_CLOSE() frees
resources allocated by VOP_OPEN().
The vnode vp will be locked on entry and should remain
locked on return.
-
-
- VOP_ACCESS(vp,
mode, cred)
- Determine the accessibility (permissions) of the file
against the specified credentials. The argument vp
is the vnode of the file to check, mode is the type
of access required and cred contains the user
credentials to check. The argument mode is a mask
which can contain VREAD, VWRITE or VEXEC. If the file is accessible in the
specified way, zero is returned, otherwise an appropriate error code is
returned.
The vnode vp will be locked on entry and should remain
locked on return.
-
-
- VOP_GETATTR(vp,
vap, cred)
- Get specific vnode attributes on a file. The argument
vp is the vnode of the file to get the attributes
for. The argument cred specifies the calling
credentials. VOP_GETATTR() uses the file system type
specific data object vp->v_data to reference the
underlying file attributes. The attributes are returned in
vap. Attributes which are not available are set to
the value VNOVAL.
For more information on vnode attributes see
vattr(9). Historically it was
considered acceptable to call VOP_GETATTR() without
first locking the vnode. This usage is deprecated.
The vnode vp will be locked on entry and should remain
locked on return.
-
-
- VOP_SETATTR(vp,
vap, cred)
- Set specific vnode attributes on a file. The argument
vp is the locked vnode of the file to set the
attributes for. The argument cred specifies the
calling credentials. VOP_SETATTR() uses the file system
type specific data object vp->v_data to reference the
underlying file attributes. The new attributes are defined in
vap. Attributes which are not being modified by
VOP_SETATTR() should be set to the value VNOVAL. If the
operation is successful zero is returned, otherwise an appropriate error
is returned.
For more information on vnode attributes see
vattr(9).
-
-
- VOP_READ(vp,
uio, ioflag,
cred)
- Read the contents of a file. The argument
vp is the vnode of the file to read from,
uio is the location to read the data into,
ioflag is a set of flags and
cred are the credentials of the calling process.
The ioflag argument is used to give directives and
hints to the file system. When attempting a read, the high 16 bits are
used to provide a read-ahead hint (in unit of file system blocks) that the
file system should attempt. The low 16 bits are a bit mask which can
contain the following flags:
- IO_UNIT
- do I/O as atomic unit
- IO_APPEND
- append write to end
- IO_SYNC
- sync I/O file integrity completion
- IO_NODELOCKED
- underlying node already locked
- IO_NDELAY
- FNDELAY flag set in file table
- IO_DSYNC
- sync I/O data integrity completion
- IO_ALTSEMANTICS
- use alternate I/O semantics
- IO_NORMAL
- operate on regular data
- IO_EXT
- operate on extended attributes
- IO_DIRECT
- do not buffer data in the kernel
Zero is returned on success, otherwise an error is returned. The vnode
should be locked on entry and remains locked on exit.
-
-
- VOP_WRITE(vp,
uio, ioflag,
cred)
- Write to a file. The argument vp is
the vnode of the file to write to, uio is the
location of the data to write, ioflag is a set of
flags and cred are the credentials of the calling
process.
The ioflag argument is used to give directives and
hints to the file system. The low 16 bits are a bit mask which can contain
the same flags as VOP_READ().
Zero is returned on success, otherwise an error is returned. The vnode
should be locked on entry and remains locked on exit.
-
-
- VOP_FALLOCATE(vp,
pos, len)
- Allocate backing store. The argument
vp is the vnode for the file. The
pos and len arguments
(specified in bytes) name an extent within the file. The blocks underlying
this range, rounding up at the top and down at the bottom if needed, are
checked; if no physical storage is allocated, a physical block is
allocated and zeroed. This operation removes “holes” from
files.
-
-
- VOP_FDISCARD(vp,
pos, len)
- Discard backing store. The argument
vp is the vnode for the file. The
pos and len arguments
(specified in bytes) name an extent within the file. The blocks underlying
this range, rounding down at the top and up at the bottom if needed, are
checked. If any physical storage is used, it is deallocated. This
operation creates “holes” in files. Discarded blocks of
regular files read back afterwards as zeroes. On devices, the underlying
discard-block operation if any (e.g. ATA TRIM) is issued. The device
handles this as it sees fit. In particular it is not
guaranteed that discarded blocks on devices will be zeroed; reading a
discarded block might produce zeros, or ones, or the previously existing
data, or some other data, or trash.
-
-
- VOP_IOCTL(vp,
command, data,
fflag, cred)
- Perform device-specific I/O. The argument
vp is the locked vnode of the file, normally
representing a device. The argument command
specifies the device-specific operation to perform and
cnp provides extra data for the specified operation.
The argument fflags is a set of flags. The argument
cred is the caller's credentials. If the operation
is successful, zero is returned, otherwise an appropriate error code is
returned.
Most file systems do not supply a function for
VOP_IOCTL(). This function implements the
ioctl(2) system call.
-
-
- VOP_FCNTL(vp,
command, data,
fflag, cred)
- Perform file control. The argument vp
is the locked vnode of the file. The argument
command specifies the operation to perform and
cnp provides extra data for the specified operation.
The argument fflags is a set of flags. The argument
cred is the caller's credentials. If the operation
is successful, zero is returned, otherwise an appropriate error code is
returned.
-
-
- VOP_POLL(vp,
events)
- Test if a poll event has occurred. The argument
vp is the vnode of the file to poll. It returns any
events of interest as specified by events that may
have occurred for the file. The argument events is a
set of flags as specified by
poll(2).
The vnode vp remains unlocked throughout the whole
operation.
-
-
- VOP_KQFILTER(vp,
kn)
- Register a knote kn with the vnode
vn. If the operation is successful zero is returned,
otherwise an appropriate error code is returned.
The vnode vp remains unlocked throughout the whole
operation.
-
-
- VOP_REVOKE(vp,
flags)
- Eliminate all activity associated with the vnode
vp. The argument flags is a
set of flags. If REVOKEALL is set in flags all
vnodes aliased to the vnode vp are also eliminated.
If the operation is successful zero is returned, otherwise an appropriate
error is returned.
The vnode vp remains unlocked throughout the whole
operation.
-
-
- VOP_MMAP(vp,
prot, cred)
- Inform file system that vp is in the
process of being memory mapped. The argument prot
specifies the vm access protection the vnode is going to be mapped with.
The argument cred is the caller's credentials. If
the file system allows the memory mapping, zero is returned, otherwise an
appropriate error code is returned.
Most file systems do not supply a function for VOP_MMAP()
and use genfs_mmap() to default for success. Only file
systems which do not integrate with the page cache at all typically want
to disallow memory mapping.
-
-
- VOP_FSYNC(vp,
cred, flags,
offlo, offhi)
- Flush pending data buffers for a file to disk. The argument
vp is the locked vnode of the file for flush. The
argument cred is the caller's credentials. The
argument flags is a set of flags. If FSYNC_WAIT is
specified in flags, the function should wait for I/O
to complete before returning. The argument offlo and
offhi specify the range of file to flush. If the
operation is successful zero is returned, otherwise an appropriate error
code is returned.
This function implements the
sync(2) and
fsync(2) system calls.
-
-
- VOP_SEEK(vp,
oldoff, newoff,
cred)
- Test if the file is seekable for the specified offset
newoff. The argument vp is the
locked vnode of the file to test. For most file systems this function
simply tests if newoff is valid. If the specified
newoff is less than zero, the function returns error
code EINVAL.
-
-
- VOP_REMOVE(dvp,
vp, cnp)
- Remove a file. The argument dvp is
the locked vnode of the directory to remove the file from and
vp is the locked vnode of the file to remove. The
argument cnp is the pathname component about the
file to remove. If the operation is successful zero is returned, otherwise
an appropriate error code is returned. Both dvp and
vp are locked on entry and are to be unlocked before
returning.
-
-
- VOP_LINK(dvp,
vp, cnp)
- Link to a file. The argument dvp is
the locked node of the directory to create the new link and
vp is the vnode of the file to be linked. The
argument cnp is the pathname component of the new
link. If the operation is successful zero is returned, otherwise an error
code is returned. The directory vnode dvp should be
locked on entry and will be released and unlocked on return. The vnode
vp should not be locked on entry and will remain
unlocked on return.
-
-
- VOP_RENAME(fdvp,
fvp, fcnp,
tdvp, tvp,
tcnp)
- Rename a file. The argument fdvp is
the vnode of the old parent directory containing in the file to be renamed
and fvp is the vnode of the file to be renamed. The
argument fcnp is the pathname component about the
file to be renamed. The argument tdvp is the vnode
of the new directory of the target file and tvp is
the vnode of the target file (if it exists). The argument
tcnp is the pathname component about the file's new
name. If the operation is successful zero is returned, otherwise an error
code is returned.
The caller must hold the target file system's rename lock. The source
directory and file vnodes should be unlocked and their reference counts
should be incremented before entry. The target directory and file vnodes
should both be locked on entry. VOP_RENAME() updates the
reference counts prior to returning.
Because of the complexity and nastiness of the interface, please do not
write new code that calls VOP_RENAME() directly until
such time as ongoing cleanup work reaches a point where the interface has
been rendered halfway sane.
-
-
- VOP_MKDIR(dvp,
vpp, cnp,
vap)
- Make a new directory in a given directory. The argument
dvp is the locked vnode of the directory to create
the new directory in and cnp is the pathname
component of the new directory. The argument vap
specifies the attributes that the new directory should be created with. If
the file is successfully created, the address of the resulting unlocked
vnode is returned in vpp and zero is returned.
This function is called after VOP_LOOKUP() when a
directory is being created. Normally, VOP_LOOKUP() will
have set the SAVENAME flag in cnp->cn_flags to keep
the memory pointed to by cnp->cn_pnbuf valid. If an
error is detected when creating the directory, this memory is released. If
the directory is created successfully it will be released unless the
SAVESTART flags in specified in cnp->cn_flags.
-
-
- VOP_RMDIR(dvp,
vp, cnp)
- Remove a directory in a given directory. The argument
dvp is the locked vnode of the directory to remove
the directory from and vp is the locked vnode of the
directory to remove. The argument cnp is the
pathname component of the directory. Zero is returned on success,
otherwise an error code is returned. Both dvp and
vp should be locked on entry and will be released
and unlocked on return.
-
-
- VOP_SYMLINK(dvp,
vpp, cnp,
vap, target)
- Create a symbolic link in a given directory. The argument
dvp is the locked vnode of the directory to create
the symbolic link in and cnp is the pathname
component of the symbolic link. The argument vap
specifies the attributes that the symbolic link should be created with and
target specifies the pathname of the target of the
symbolic link. If the symbolic link is successfully created, the address
of the resulting unlocked vnode is returned in vpp
and zero is returned.
This function is called after VOP_LOOKUP() when a symbolic
link is being created. Normally, VOP_LOOKUP() will have
set the SAVENAME flag in cnp->cn_flags to keep the
memory pointed to by cnp->cn_pnbuf valid. If an error
is detected when creating the symbolic link, this memory is released. If
the symbolic link is created successfully it will be released unless the
SAVESTART flags in specified in cnp->cn_flags.
-
-
- VOP_READDIR(vp,
uio, cred,
eofflag, cookies,
ncookies)
- Read directory entry. The argument vp
is the vnode of the directory to read the contents of and
uio is the destination location to read the contents
into. The argument cred is the caller's credentials.
The argument eofflag is the pointer to a flag which
is set by VOP_READDIR() to indicate an end-of-file
condition. If eofflag is
NULL
, the end-of-file condition is not returned.
The arguments cookies and
ncookies specify the addresses for the list and
number of directory seek cookies generated for NFS. Both
cookies and ncookies should be
NULL
if they aren't required to be returned by
VOP_READDIR(). The directory contents are read into
struct dirent structures and uio->uio_offset is
set to the offset of the next unread directory entry. This offset may be
used in a following invocation to continue a sequential read of the
directory contents. If the operation is successful zero is returned,
otherwise an appropriate error code is returned.
The directory should be locked on entry and will remain locked on return.
In case ncookies and cookies are
supplied, one cookie should be returned per directory entry. The value of
the cookie for each directory entry should be the offset within the
directory where the on-disk version of the following directory entry
starts. That is, for each directory entry i, the
corresponding cookie should refer to the offset of directory entry
i + 1.
Note that the cookies array must be allocated by the
callee using the M_TEMP malloc type as callers of
VOP_READDIR() must be able to free the allocation.
-
-
- VOP_READLINK(vp,
uio, cred)
- Read the contents of a symbolic link. The argument
vp is the locked vnode of the symlink and
uio is the destination location to read the contents
into. The argument cred is the credentials of the
caller. If the operation is successful zero is returned, otherwise an
error code is returned.
The vnode should be locked on entry and will remain locked on return.
-
-
- VOP_ABORTOP(dvp,
cnp)
- Abort pending operation on vnode dvp
and free resources allocated in cnp.
This operation is rarely implemented in file systems and
genfs_abortop() is typically used instead.
-
-
- VOP_INACTIVE(vp)
- Release the inactive vnode.
VOP_INACTIVE() is called when the kernel is no longer
using the vnode. This may be because the reference count reaches zero or
it may be that the file system is being forcibly unmounted while there are
open files. It can be used to reclaim space for open but deleted files.
The argument vp is the locked vnode to be released.
If the operation is successful zero is returned, otherwise an appropriate
error code is returned. The vnode vp must be locked
on entry, and will remain locked on return.
-
-
- VOP_RECLAIM(vp)
- Reclaim the vnode for another file system.
VOP_RECLAIM() is called when a vnode is being reused for
a different file system. Any file system specific resources associated
with the vnode should be freed. The argument vp is
the vnode to be reclaimed. If the operation is successful zero is
returned, otherwise an appropriate error code is returned. The vnode
vp should not be locked on entry, and will remain
unlocked on return.
-
-
- VOP_LOCK(vp,
flags)
- Sleep until vnode lock is free. The argument
vp is the vnode of the file to be locked. The
argument flags is
LK_EXCLUSIVE
to take the lock exclusively or
LK_SHARED
to take a shared lock. If
flags contains LK_NOWAIT
and
the lock is busy, the operation will return immediately with an error
code. If flags contains
LK_RETRY
this is a hint the caller wants the lock
on dead vnodes too. If the operation is successful zero is returned,
otherwise an appropriate error code is returned.
VOP_LOCK() is used to serialize access to the file
system such as to prevent two writes to the same file from happening at
the same time. Kernel code should use
vn_lock(9) to lock a vnode
rather than calling VOP_LOCK() directly.
-
-
- VOP_UNLOCK(vp)
- Wake up process sleeping on lock. The argument
vp is the vnode of the file to be unlocked. If the
operation is successful zero is returned, otherwise an appropriate error
code is returned. VOP_UNLOCK() is used to serialize
access to the file system such as to prevent two writes to the same file
from happening at the same time.
-
-
- VOP_ISLOCKED(vp)
- Test if the vnode vp is locked.
Possible return values are
LK_EXCLUSIVE
,
LK_SHARED
or 0 for lock held exclusively by the
calling thread, shared lock held by anyone or unlocked, respectively.
This function must never be used to make locking decisions at run time: it
is provided only for diagnostic purposes.
-
-
- VOP_BMAP(vp,
bn, vpp,
bnp, runp)
- Convert the logical block number bn
of a file specified by vnode vp to its physical
block number on the disk. The physical block is returned in
bnp. In case the logical block is not allocated, -1
is used.
If vpp is not
NULL
, the vnode
of the device vnode for the file system is returned in the address
specified by vpp. If runp is
not NULL
, the number of contiguous blocks starting
from the next block after the queried block will be returned in
runp.
-
-
- VOP_PRINT(vp)
- Print debugging information. The argument
vp is the vnode to print. If the operation is
successful zero is returned, otherwise an appropriate error code is
returned.
-
-
- VOP_PATHCONF(vp,
name, retval)
- Implement POSIX
pathconf(2) and
fpathconf(2) support. The
argument vp is the locked vnode to get information
about. The argument name specified the type of
information to return. The information is returned in the address
specified by retval. Valid values for
name are:
- _PC_LINK_MAX
- return the maximum number of links to a file
- _PC_NAME_MAX
- return the maximum number of bytes in a file name
- _PC_PATH_MAX
- return the maximum number of bytes in a pathname
- _PC_PIPE_BUF
- return the maximum number of bytes which will be
written atomically to a pipe
- _PC_CHOWN_RESTRICTED
- return 1 if appropriate privileges are required for the
chown(2) system call,
otherwise zero
- _PC_NO_TRUNC
- return 0 if file names longer than
{
NAME_MAX
} are silently truncated
If name is recognized, *retval
is set to the specified value and zero is returned, otherwise an
appropriate error is returned.
-
-
- VOP_ADVLOCK(vp,
id, op,
fl, flags)
- Manipulate Advisory record locks on a vnode. The argument
vp is the vnode on which locks are manipulated. The
argument id is the id token which is changing the
lock and op is the
fcntl(2) operation to
perform. Valid values are:
- F_SETLK
- set lock
- F_GETLK
- get the first conflicted lock
- F_UNLCK
- clear lock
The argument fl is a description of the lock. In the
case of SEEK_CUR
, The caller should add the
current file offset to fl->l_start beforehand.
VOP_ADVLOCK() treats SEEK_CUR
as
SEEK_SET
.
The argument flags is the set of flags. Valid values
are:
- F_WAIT
- wait until lock is granted
- F_FLOCK
- use
flock(2) semantics for
lock
- F_POSIX
- use POSIX semantics for lock
If the operation is successful zero is returned, otherwise an appropriate
error is returned.
-
-
- VOP_WHITEOUT(dvp,
cnp, flags)
- Whiteout pathname component in directory with vnode
dvp. The argument cnp
specifies the pathname component to whiteout.
The vnode dvp should be locked on entry and will
remain locked on return.
-
-
- VOP_GETPAGES(vp,
offset, m,
count, centeridx,
access_type, advice,
flags)
- Read VM pages from file. The argument
vp is the locked vnode to read the VM pages from.
The argument offset is offset in the file to start
accessing and m is an array of VM pages. The
argument count points a variable that specifies the
number of pages to read. If the operation is successful zero is returned,
otherwise an appropriate error code is returned. If PGO_LOCKED is
specified in flags, VOP_GETPAGES()
might return less pages than requested. In that case, the variable pointed
to by count will be updated.
This function is primarily used by the page-fault handing mechanism.
-
-
- VOP_PUTPAGES(vp,
offlo, offhi,
flags)
- Write modified (dirty) VM pages to file. The argument
vp is the vnode to write the VM pages to. The
vnode's vm object lock (v_uobj.vmobjlock) must be
held by the caller and will be released upon return. The arguments
offlo and offhi specify the
range of VM pages to write. In case offhi is given
as 0, all pages at and after the start offset offlo
belonging the vnode vp will be written. The argument
flags controls the behavior of the routine and takes
the vm pager's flags (
PGO_ -prefixed
). If the
operation is successful zero is returned, otherwise an appropriate error
code is returned.
The function is primarily used by the pageout handling mechanism and is
commonly implemented indirectly by genfs_putpages() with
the help of VOP_STRATEGY() and
VOP_BMAP().
-
-
- VOP_STRATEGY(vp,
bp)
- Read/write a file system buffer. The argument
vp is the vnode to read/write to. The argument
bp is the buffer to be read or written.
VOP_STRATEGY() will either read or write data to the
file depending on the value of bp->b_flags. If the
operation is successful zero is returned, otherwise an appropriate error
code is returned.
-
-
- VOP_BWRITE(vp,
bp)
- Write a file system buffer. The argument
vp is the vnode to write to. The argument
bp specifies the buffer to be written. If the
operation is successful zero is returned, otherwise an appropriate error
code is returned.
-
-
- VOP_GETEXTATTR(vp,
attrnamespace, name,
uio, size,
cred)
- Get an extended attribute. The argument
vp is the locked vnode of the file or directory from
which to retrieve the attribute. The argument
attrnamespace specifies the extended attribute
namespace. The argument name is a nul-terminated
character string naming the attribute to retrieve. The argument
uio, if not
NULL
, specifies
where the extended attribute value is to be written. The argument
size, if not NULL
, will
contain the number of bytes required to read all of the attribute data
upon return. In most cases, uio will be
NULL
when size is not, and
vice versa. The argument cred specifies the user
credentials to use when authorizing the request.
-
-
- VOP_SETEXTATTR(vp,
attrnamespace, name,
uio, cred)
- Set an extended attribute. The argument
vp is the locked vnode of the file or directory to
which to store the attribute. The argument namespace
specifies the extended attribute namespace. The argument
name is a nul-terminated character string naming the
attribute to store. The argument uio specifies the
source of the extended attribute data. The argument
cred specifies the user credentials to use when
authorizing the request.
-
-
- VOP_LISTEXTATTR(vp,
attrnamespace, uio,
size, cred)
- Retrieve the list of extended attributes. The argument
vp is the locked vnode of the file or directory
whose attributes are to be listed. The argument
attrnamespace specifies the extended attribute
namespace. The argument uio, if not
NULL
, specifies where the extended attribute list
is to be written. The argument size, if not
NULL
, will contain the number of bytes required to
read all of the attribute names upon return. In most cases,
uio will be NULL
when
size is not, and vice versa. The argument
cred specifies the user credentials to use when
authorizing the request.
-
-
- VOP_DELETEEXTATTR(vp,
attrnamespace, name,
cred)
- Remove attribute name from file
associated with vp. The argument
attrnamespace specifies the extended attribute
namespace. If full removal is not supported, the file system should return
EOPNOTSUPP
to allow the caller to zero out the
value with VOP_SETEXTATTR().
The vnode vp should be locked on entry and will remain
locked on return.
FILES
src/sys/kern/vnode_if.src contains the list of vnode
functions, their definitions and an exact locking protocol.
ERRORS
-
-
- [
EACCES
]
- Access for the specified operation is denied.
-
-
- [
EDQUOT
]
- Quota exceeded.
-
-
- [
EINVAL
]
- attempt to read from an illegal offset in the directory;
unrecognized input
-
-
- [
EIO
]
- a read error occurred while reading the directory or
reading the contents of a symbolic link
-
-
- [
EJUSTRETURN
]
- A CREATE or RENAME operation would be successful.
-
-
- [
ENOATTR
]
- The requested attribute is not defined for this vnode.
-
-
- [
ENOENT
]
- The component was not found in the directory.
-
-
- [
ENOSPC
]
- The file system is full.
-
-
- [
ENOTDIR
]
- The vnode does not represent a directory.
-
-
- [
ENOTEMPTY
]
- attempt to remove a directory which is not empty
-
-
- [
EPERM
]
- an attempt was made to change an immutable file
-
-
- [
EROFS
]
- the file system is read-only
SEE ALSO
extattr(9),
intro(9),
namei(9),
vattr(9),
vfs(9),
vfsops(9),
vnode(9)
HISTORY
The vnode operations vector, its functions and the corresponding macros appeared
in
4.3BSD.