VNODEOPS(9) | Kernel Developer's Manual | VNODEOPS(9) |
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
—
#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.
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:
Valid values for cn->cn_flags are:
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).
VOP_LOOKUP
(dvp,
vpp, cnp)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)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)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)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)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)The vnode vp will be locked on entry and should remain locked on return.
VOP_GETATTR
(vp,
vap, cred)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)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)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:
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)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)VOP_FDISCARD
(vp,
pos, len)VOP_IOCTL
(vp,
command, data,
fflag, cred)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)VOP_POLL
(vp,
events)The vnode vp remains unlocked throughout the whole operation.
VOP_KQFILTER
(vp,
kn)The vnode vp remains unlocked throughout the whole operation.
VOP_REVOKE
(vp,
flags)The vnode vp remains unlocked throughout the whole operation.
VOP_MMAP
(vp,
prot, cred)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)This function implements the sync(2) and fsync(2) system calls.
VOP_SEEK
(vp,
oldoff, newoff,
cred)VOP_REMOVE
(dvp,
vp, cnp)VOP_LINK
(dvp,
vp, cnp)VOP_RENAME
(fdvp,
fvp, fcnp,
tdvp, tvp,
tcnp)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)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)VOP_SYMLINK
(dvp,
vpp, cnp,
vap, target)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)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)The vnode should be locked on entry and will remain locked on return.
VOP_ABORTOP
(dvp,
cnp)This operation is rarely implemented in file systems and
genfs_abortop
() is typically used instead.
VOP_INACTIVE
(vp)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)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 be locked on entry,
and will be returned unlocked.VOP_LOCK
(vp,
flags)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)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)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)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)VOP_PATHCONF
(vp,
name, retval)NAME_MAX
}
are silently truncatedIf 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)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:
If the operation is successful zero is returned, otherwise an appropriate error is returned.
VOP_WHITEOUT
(dvp,
cnp, flags)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)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)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)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)VOP_GETEXTATTR
(vp,
attrnamespace, name,
uio, size,
cred)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)VOP_LISTEXTATTR
(vp,
attrnamespace, uio,
size, cred)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)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.
EACCES
]EDQUOT
]EINVAL
]EIO
]EJUSTRETURN
]ENOATTR
]ENOENT
]ENOSPC
]ENOTDIR
]ENOTEMPTY
]EPERM
]EROFS
]November 19, 2017 | NetBSD 9.0 |