diff options
Diffstat (limited to 'share/man/man9/VOP_LOOKUP.9')
| -rw-r--r-- | share/man/man9/VOP_LOOKUP.9 | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/share/man/man9/VOP_LOOKUP.9 b/share/man/man9/VOP_LOOKUP.9 new file mode 100644 index 00000000000..f09d471b124 --- /dev/null +++ b/share/man/man9/VOP_LOOKUP.9 @@ -0,0 +1,435 @@ +.\" $OpenBSD: VOP_LOOKUP.9,v 1.11 2003/07/25 02:27:33 deraadt Exp $ +.\" +.\" Copyright (c) 2003 Ted Unangst +.\" All rights reserved. +.\" +.\" 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 AUTHOR ``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 AUTHOR 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 March 9, 2003 +.Dt VOP_LOOKUP 9 +.Os +.Sh NAME +.Nm VOP functions +.Nd vnode operations +.Sh SYNOPSIS +.Fd #include <sys/vnode.h> +.Ft int +.Fo VOP_CREATE +.Fa "struct vnode *dvp" +.Fa "struct vnode **vpp" +.Fa "struct componentname *cnp" +.Fa "struct vattr *vap" +.Fc +.Ft int +.Fo VOP_FSYNC +.Fa "struct vnode *vp" +.Fa "struct ucred *cred" +.Fa "int waitfor" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_GETEXTATTR +.Fa "struct vnode *vp" +.Fa "int attrnamespace" +.Fa "const char *name" +.Fa "struct uio *uio" +.Fa "size_t *size" +.Fa "struct ucred *cred" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_ISLOCKED +.Fa "struct vnode *" +.Fc +.Ft int +.Fo VOP_LINK +.Fa "struct vnode *dvp" +.Fa "struct vnode *vp" +.Fa "struct componentname *cnp" +.Fc +.Ft int +.Fo VOP_LOCK +.Fa "struct vnode *vp" +.Fa "int flags" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_LOOKUP +.Fa "struct vnode *dvp" +.Fa "struct vnode **vpp" +.Fa "struct componentname *cnp" +.Fc +.Ft int +.Fo VOP_MKDIR +.Fa "struct vnode *dvp" +.Fa "struct vnode **vpp" +.Fa "struct componentname *cnp" +.Fa "struct vattr *vap" +.Fc +.Ft int +.Fo VOP_PRINT +.Fa "struct vnode *vp" +.Fc +.Ft int +.Fo VOP_READLINK +.Fa "struct vnode *vp" +.Fa "struct uio *uio" +.Fa "struct ucred *cred" +.Fc +.Ft int +.Fo VOP_REALLOCBLKS +.Fa "struct vnode *vp" +.Fa "struct cluster_save *buflist" +.Fc +.Ft int +.Fo VOP_RECLAIM +.Fa "struct vnode *vp" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_REMOVE +.Fa "struct vnode *dvp" +.Fa "struct vnode *vp" +.Fa "struct componentname *cnp" +.Fc +.Ft int +.Fo VOP_REVOKE +.Fa "struct vnode *vp" +.Fa "int flags" +.Fc +.Ft int +.Fo VOP_RMDIR +.Fa "struct vnode *dvp" +.Fa "struct vnode *vp" +.Fa "struct componentname *cnp" +.Fc +.Ft int +.Fo VOP_SETEXTATTR +.Fa "struct vnode *vp" +.Fa "int attrnamespace" +.Fa "const char *name" +.Fa "struct uio *uio" +.Fa "struct ucred *cred" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_STRATEGY +.Fa "struct buf *bp" +.Fc +.Ft int +.Fo VOP_SYMLINK +.Fa "struct vnode *dvp" +.Fa "struct vnode *vpp" +.Fa "struct componentname *cnp" +.Fa "struct vattr *vap" +.Fa "char *target" +.Fc +.Ft int +.Fo VOP_UNLOCK +.Fa "struct vnode *vp" +.Fa "int flags" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_WHITEOUT +.Fa "struct vnode *dvp" +.Fa "struct componentname *cnp" +.Fa "int flags" +.Fc +.\" and many more +.Sh DESCRIPTION +The +.Nm +functions implement a generic way to perform operations on vnodes. +The VOP function called passes the arguments to the correct file system +specific function. +Not all file systems implement all operations, in which case a generic +method will be used. +These functions exist to provide an abstract method to invoke vnode +operations without needing to know anything about the underlying file system. +Many syscalls map directly to a specific VOP function. +.Pp +The arguments for each VOP +function consist of one or more vnode pointers along with other data +needed to perform the operation. +Care must be taken to obey the vnode locking discipline when using +VOP functions. +The locking discipline for all currently defined VOP +functions is described in the file +.Pa sys/kern/vnode_if.src . +Many VOP calls take a struct proc *p argument. +This should be the current process. +VOP calls are not safe to call in an interrupt context. +.Pp +The following sections comment on the VOP functions from the consumer's +perspective. +Some notes for file system implementors follow. +.Sh VOP_CREATE +.Fn VOP_CREATE +creates a new directory entry for a regular file in the directory +.Ar dvp +and returns a locked, referenced vnode in +.Ar vpp . +The file name is in +.Ar cnp +and its permissions will be +.Ar vap . +.Sh VOP_FSYNC +.Fn VOP_FSYNC +flushes any dirty buffers associated with +.Ar vp +to disk. +The vnode is locked on entry and exit. +.Ar waitfor +can be set to MNT_WAIT to indicate VOP_FSYNC should not return +until all data is written. +.Sh VOP_GETEXTATTR +.Fn VOP_GETEXTATTR +and +.Fn VOP_SETEXTATTR +are called to get and set named extended file attributes (see +.Xr extattr 9 ) . +.Ar vp +is the vnode for which to get or set the attribute. +It must be locked. +.Ar attrnamespace +is an integer describing whether the attribute belongs in the +user or system namespace. +.Ar name +is the extended attribute to get or set. +.Ar uio +is a +.Xr uio 9 +structure with the userland address containing the userland data. +VOP_GETEXTATTR will return the actual length of the attribute +in +.Ar size +if it is non-NULL. +.Ar cred +is a pointer to the credentials used to access the file. +.Sh VOP_LINK +.Fn VOP_LINK +increases the link count for the vnode +.Ar vp . +A new entry with name +.Ar cnp +should be added to the directory +.Ar dvp . +.Ar dvp +is locked on entry and unlocked on exit. +.Sh VOP_LOOKUP +.Fn VOP_LOOKUP +finds the file corresponding to the name +.Ar cnp +in the directory +.Ar dvp +and returns a vnode in +.Ar vpp . +.Ar dvp +is locked on entry and exit, and +.Ar vpp +is locked upon a successful return. +.Ar vpp +will be NULL on error, and cnp->cn_flags will be set to PDIRUNLOCK +if +.Ar dvp +has been unlocked for an unsuccessful return. +.Sh VOP_MKDIR +.Fn VOP_MKDIR +implements the +.Xr mkdir 2 +syscall. +A new directory with name matching that in +.Ar cnp +and with permissions +.Ar vattr +will be created in the directory +.Ar dvp . +On success, the new vnode is returned locked in +.Ar vpp . +.Ar dvp +must be locked on entry and is unlocked on exit. +.Sh VOP_PRINT +.Fn VOP_PRINT +prints information about the vnode to the kernel message buffer. +It is not used normally, but exists only for debugging purposes. +.Sh VOP_READLINK +.Fn VOP_READLINK +reads a symbolic link and returns the target's name in +.Ar uio . +.Ar vp +is locked on entry and exit and must be a symlink. +.Sh VOP_REALLOCBLKS +.Fn VOP_REALLOCBLKS +is called by the vfs write clustering code. +It gives the file system an opporunity to rearrange the on disk blocks +for a file to reduce fragmentation. +.Ar vp +is the locked vnode for the file, and +.Ar buflist +is a cluster of the outstanding buffers about to written. +Currently, only FFS implements this call. +.Sh VOP_RECLAIM +.Fn VOP_RECLAIM +is used by +.Xr vclean 9 +so that the file system has an opportunity to free memory +and perform any other cleanup activity related to +.Ar vp . +.Ar vp +is unlocked on entry and exit. +VOP_RECLAIM should not be used by generic code. +.Sh VOP_REMOVE +.Fn VOP_REMOVE +removes the link named +.Ar cnp +from the directory +.Ar dvp . +This file corresponds to the vnode +.Ar vp . +Both dvp and vp are locked on entry and unlocked on exit, and +each has its reference count decremented by one. +VOP_REMOVE does not delete the file from disk unless its link count +becomes zero (for file systems which support multiple links). +.Sh VOP_REVOKE +.Fn VOP_REVOKE +is used by the +.Xr revoke 2 +syscall to prevent any further access to a vnode. +The vnode ops will be changed to those of deadfs, which returns only +errors. +.Ar vp +must be unlocked. +.Sh VOP_RMDIR +.Fn VOP_RMDIR +implements the +.Xr rmdir 2 +syscall. +The directory +.Ar vp +will be removed from the directory +.Ar dvp . +Both are locked on entry and unlocked on exit. +The name of the directory for removal is additionally contained in +.Ar cnp . +.Sh VOP_STRATEGY +.Fn VOP_STRATEGY +is the only VOP call not taking a vnode argument. +It calls the appropriate strategy function for the device backing the +buffer's vnode. +.Sh VOP_SYMLINK +.Fn VOP_SYMLINK +creates a symbolic link with name +.Ar cnp +in the directory +.Ar dvp +with mode +.Ar vap . +The link will point to +.Ar target +and a vnode for it is returned in +.Ar vpp . +The directory vnode is locked on entry and unlocked on exit. +Note that unlike most VOP calls returning a vnode, VOP_SYMLINK +does not lock or reference +.Ar vpp . +.Sh VOP_LOCK +.Fn VOP_LOCK +is used internally by +.Xr vn_lock 9 +to lock a vnode. +It should not be used by other file system code. +.Fn VOP_UNLOCK +unlocks a vnode. +.Ar flags +should be zero in most cases. +.Fn VOP_ISLOCKED +returns 1 if +.Ar vp +is locked and 0 if not. +It should be used cautiously, as not all file systems implement locks +effectively. +Note the asymmetry between vn_lock and VOP_UNLOCK. +.Sh VOP_WHITEOUT +.Fn VOP_WHITEOUT +manipulates whiteout entries in a directory. +.Ar dvp +is the directory containing, or to contain, the whiteout. +It is locked on entry and exit. +.Ar cnp +contains the name of the whiteout. +.Ar flags +is used to indicate the operation. +Whiteouts may be created or deleted. +A whiteout entry is normally used to indicate the absence of a file on a +translucent file system. +.Sh IMPLEMENTATION NOTES +The +.Nm VOP +functions are stubs which redirect their arguments to the +appropriate function for each file system. +In order to allow for layered file systems and generic bypass methods, +all vnode operation implementing functions take only a single void * +pointer as an argument. +This points to a structure containing the real arguments. +Additionally, this structure contains a struct vnodeop_desc *, +or vnodeop description. +The description is typically used by the abstract VOP code, but can +be useful to the lower implementation as well. +Every file system defines an array of struct vnodeopv_entry_desc +that contains one entry for each implemented vnode op. +Unimplemented vnode operations match the default description, +.Em vop_default_desc . +Most non-layer file systems should assign the default error handler, +.Em vn_default_error , +to the generic description. +.Pp +All lower level implementations should conform to the interfaces described +above. +The rules for locking and referencing vnodes are enforced by each +file system implementation, not the VOP stubs. +.Sh RETURN VALUES +The +.Nm +functions return 0 to indicate success and a non-zero error code +to indicate failure. +.Sh FILES +.Bl -tag -width sys/kern/vnode_if.src -compact +.It Pa sys/kern/vnode_if.src +source file containing +.Nm +definitions +.It Pa sys/kern/vnode_if.c +C file with implementations of each +.Nm +stub call +.El +.Sh SEE ALSO +.Xr errno 2 , +.Xr vn_lock 9 , +.Xr vnode 9 +.Sh AUTHORS +This man page was written by Ted Unangst for +.Ox . +.Sh BUGS +The locking discipline is too complex. +Refer to +.Xr vn_lock 9 . |