From f383f976d5be8c65bab8da070662f1e88db2c99c Mon Sep 17 00:00:00 2001 From: mickey Date: Thu, 24 Jul 2003 20:15:44 +0000 Subject: rename VOP_LOOKUP.9 into vnodeops.9 for nicer xreffing. a few pages i wrote being high on acetyl salicylic acid. vfs(9) from netbsd. --- share/man/man9/Makefile | 40 ++-- share/man/man9/VOP_LOOKUP.9 | 435 -------------------------------------------- share/man/man9/ktrace.9 | 177 ++++++++++++++++++ share/man/man9/namei.9 | 10 +- share/man/man9/syscall.9 | 253 ++++++++++++++++++++++++++ share/man/man9/systrace.9 | 89 +++++++++ share/man/man9/vfs.9 | 64 +++++++ share/man/man9/vnodeops.9 | 435 ++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 1046 insertions(+), 457 deletions(-) delete mode 100644 share/man/man9/VOP_LOOKUP.9 create mode 100644 share/man/man9/ktrace.9 create mode 100644 share/man/man9/syscall.9 create mode 100644 share/man/man9/systrace.9 create mode 100644 share/man/man9/vfs.9 create mode 100644 share/man/man9/vnodeops.9 (limited to 'share/man/man9') diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index dab29d43836..40c00f4a2b3 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.73 2003/07/21 21:00:49 mickey Exp $ +# $OpenBSD: Makefile,v 1.74 2003/07/24 20:15:44 mickey Exp $ # $NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -9,17 +9,17 @@ MAN= altq.9 audio.9 autoconf.9 boot.9 bus_dma.9 bus_space.9 \ extattr.9 file.9 \ fork1.9 extent.9 getdevvp.9 getnewvnode.9 hash.9 hashinit.9 \ hardclock.9 hook_establish.9 hz.9 hzto.9 intro.9 inittodr.9 log.9 \ - kern.9 knote.9 kthread.9 lock.9 \ - malloc.9 mbuf.9 mbuf_tags.9 md5.9 microtime.9 \ + kern.9 knote.9 kthread.9 ktrace.9 lock.9 \ + malloc.9 mbuf.9 mbuf_tags.9 md5.9 microtime.9 namei.9 \ panic.9 pfind.9 physio.9 pmap.9 \ pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \ radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 \ shutdownhook_establish.9 sleep.9 spl.9 startuphook_establish.9 \ - style.9 \ - time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 \ + style.9 syscall.9 systrace.9 \ + time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 \ vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 vget.9 \ - vgone.9 vhold.9 vinvalbuf.9 VOP_LOOKUP.9 vput.9 vref.9 vrele.9 \ - vnode.9 vn_lock.9 vrecycle.9 vwaitforio.9 + vgone.9 vhold.9 vinvalbuf.9 vput.9 vref.9 vrele.9 \ + vnode.9 vnodeops.9 vn_lock.9 vrecycle.9 vwaitforio.9 MLINKS+=autoconf.9 config_init.9 autoconf.9 config_search.9 \ autoconf.9 config_rootsearch.9 autoconf.9 config_found_sm.9 \ @@ -111,6 +111,9 @@ MLINKS+=hz.9 tick.9 hz.9 tickadj.9 hz.9 stathz.9 hz.9 profhz.9 MLINKS+=knote.9 KNOTE.9 MLINKS+=kthread.9 kthread_create.9 kthread.9 kthread_exit.9 \ kthread.9 kthread_create_deferred.9 +MLINKS+=ktrace.9 ktrcsw.9 ktrace.9 ktremul.9 ktrace.9 ktrgenio.9 \ + ktrace.9 ktrnamei.9 ktrace.9 ktrpsig.9 ktrace.9 ktrsyscall.9 \ + ktrace.9 ktrsysret.9 ktrace.9 KTRPOINT.9 MLINKS+=lock.9 lockinit.9 lock.9 lockmgr.9 lock.9 lockstatus.9 \ lock.9 lockmgr_printinfo.9 \ lock.9 simple_lock_init.9 lock.9 simple_lock.9 \ @@ -128,6 +131,7 @@ MLINKS+=mbuf.9 m_copym2.9 mbuf.9 m_copym.9 mbuf.9 m_free.9 mbuf.9 MFREE.9 \ mbuf.9 MEXTALLOC.9 mbuf.9 MCLGET.9 mbuf.9 MEXTADD.9 mbuf.9 M_ALIGN.9 \ mbuf.9 MH_ALIGN.9 mbuf.9 M_READONLY.9 mbuf.9 M_LEADINGSPACE.9 \ mbuf.9 M_TRAILINGSPACE.9 mbuf.9 MCHTYPE.9 +MLINKS+=namei.9 lookup.9 namei.9 relookup.9 namei.9 NDINIT.9 MLINKS+=random.9 add_true_randomness.9 \ random.9 add_timer_randomness.9 \ random.9 add_mouse_randomness.9 \ @@ -162,6 +166,8 @@ MLINKS+=spl.9 spl0.9 spl.9 splassert.9 spl.9 splbio.9 spl.9 splclock.9 \ spl.9 splsoftnet.9 spl.9 splsoftserial.9 spl.9 splsofttty.9 \ spl.9 splstatclock.9 spl.9 spltty.9 spl.9 splvm.9 spl.9 splx.9 MLINKS+=startuphook_establish.9 startuphook_disestablish.9 +MLINKS+=systrace.9 systrace_redirect.9 \ + systrace.9 systrace_fork.9 systrace.9 systrace_exit.9 MLINKS+=time.9 boottime.9 time.9 mono_time.9 time.9 runtime.9 MLINKS+=timeout.9 timeout_add.9 timeout.9 timeout_set.9 \ timeout.9 timeout_pending.9 timeout.9 timeout_del.9 \ @@ -201,15 +207,15 @@ MLINKS+=kern.9 imax.9 kern.9 imin.9 kern.9 lmax.9 kern.9 lmin.9 \ kern.9 srandom.9 kern.9 getsn.9 # VOP functions -MLINKS+=VOP_LOOKUP.9 VOP_CREATE.9 VOP_LOOKUP.9 VOP_FSYNC.9 \ - VOP_LOOKUP.9 VOP_GETEXTATTR.9 VOP_LOOKUP.9 VOP_ISLOCKED.9 \ - VOP_LOOKUP.9 VOP_LINK.9 VOP_LOOKUP.9 VOP_LOCK.9 \ - VOP_LOOKUP.9 VOP_MKDIR.9 VOP_LOOKUP.9 VOP_PRINT.9 \ - VOP_LOOKUP.9 VOP_READLINK.9 VOP_LOOKUP.9 VOP_REALOCBLKS.9 \ - VOP_LOOKUP.9 VOP_RECLAIM.9 VOP_LOOKUP.9 VOP_REMOVE.9 \ - VOP_LOOKUP.9 VOP_REVOKE.9 VOP_LOOKUP.9 VOP_RMDIR.9 \ - VOP_LOOKUP.9 VOP_SETEXTATTR.9 VOP_LOOKUP.9 VOP_STRATEGY.9 \ - VOP_LOOKUP.9 VOP_SYMLINK.9 VOP_LOOKUP.9 VOP_UNLOCK.9 \ - VOP_LOOKUP.9 VOP_WHITEOUT.9 +MLINKS+=vnodeops.9 VOP_CREATE.9 vnodeops.9 VOP_FSYNC.9 \ + vnodeops.9 VOP_GETEXTATTR.9 vnodeops.9 VOP_ISLOCKED.9 \ + vnodeops.9 VOP_LOOKUP.9 vnodeops.9 VOP_LINK.9 vnodeops.9 VOP_LOCK.9 \ + vnodeops.9 VOP_MKDIR.9 vnodeops.9 VOP_PRINT.9 \ + vnodeops.9 VOP_READLINK.9 vnodeops.9 VOP_REALOCBLKS.9 \ + vnodeops.9 VOP_RECLAIM.9 vnodeops.9 VOP_REMOVE.9 \ + vnodeops.9 VOP_REVOKE.9 vnodeops.9 VOP_RMDIR.9 \ + vnodeops.9 VOP_SETEXTATTR.9 vnodeops.9 VOP_STRATEGY.9 \ + vnodeops.9 VOP_SYMLINK.9 vnodeops.9 VOP_UNLOCK.9 \ + vnodeops.9 VOP_WHITEOUT.9 .include diff --git a/share/man/man9/VOP_LOOKUP.9 b/share/man/man9/VOP_LOOKUP.9 deleted file mode 100644 index 28c1c5a4cab..00000000000 --- a/share/man/man9/VOP_LOOKUP.9 +++ /dev/null @@ -1,435 +0,0 @@ -.\" $OpenBSD: VOP_LOOKUP.9,v 1.9 2003/06/06 20:56:32 jmc 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 9 -.Os -.Sh NAME -.Nm VOP functions -.Nd vnode operations -.Sh SYNOPSIS -.Fd #include -.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 . diff --git a/share/man/man9/ktrace.9 b/share/man/man9/ktrace.9 new file mode 100644 index 00000000000..025065935de --- /dev/null +++ b/share/man/man9/ktrace.9 @@ -0,0 +1,177 @@ +.\" $OpenBSD: ktrace.9,v 1.1 2003/07/24 20:15:45 mickey Exp $ +.\" +.\" Copyright (c) 2003 Michael Shalayeff +.\" +.\" 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 REGENTS 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 REGENTS 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 MIND, 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 July 21, 2003 +.Dt KTRACE 9 +.Os +.Sh NAME +.Nm ktrcsw , +.Nm ktremul , +.Nm ktrgenio , +.Nm ktrnamei , +.Nm ktrpsig , +.Nm ktrsyscall , +.Nm ktrsysret , +.Nm KTRPOINT +.Nd "process tracing kernel interface" +.Sh SYNOPSIS +.In sys/ktrace.h +.Fn KTRPOINT "struct proc *p" "int type" +.Ft void +.Fn ktrcsw "struct proc *p" "int out" "int user" +.Ft void +.Fn ktremul "struct proc *p" "char *emul" +.Ft void +.Fn ktrgenio "struct proc *p" "int fd" "enum uio_rw rw" "struct iovec *iov" "int len" "int error" +.Ft void +.Fn ktrnamei "struct proc *p" "char *path" +.Ft void +.Fn ktrpsig "struct proc *p" "int sig" "sig_t action" "int mask" "int code" "siginfo_t *si" +.Ft void +.Fn ktrsyscall "struct proc *p" "register_t code" "size_t argsize" "register_t args[]" +.Ft void +.Fn ktrsysret "struct proc *p" "register_t code" "int error" "register_t retval" +.Sh DESCRIPTION +This interface is ment for kernel subsystems and machine dependent code +to inform the user about the events occuring to the process should +tracing of such be enabled using the +.Xr ktrace 2 +system call. +Each of the functions (except for +.Nm KTRPOINT ) +is ment for a particular type of events and is described below. +.Pp +.Fn KTRPOINT +macro should be used before calling any of the other tracing functions +to verify that tracing for that particular type of events has been enabled. +Possible values for the +.Fa type +argument are a mask of the KTRFAC_ values described in +.Xr ktrace 2 . +.Pp +.Fn ktrcsw +is called during the context switching. +The +.Fa user +argument is a boolean value specifing whether process has +been put into a waiting state (true) or placed onto a running queue (false). +Furthemore the +.Fa user +argument indicates whether a voluntary (false) or an involuntary (true) +switching has happened. +.Pp +.Fn ktremul +should be called every time emulation for the execution environment +is changed and thus the name of which is given in the +.Fa name +argument. +.Pp +.Fn ktrgenio +should be called for each generic input/output transactions that is +described by the +.Fa fd +file descriptor, +.Fa rw +transaction type (consult +.Pa sys/sys/uio.h +for the +.Nm enum uio_rw +definition), +.Fa iov +input/output data vector, +.Fa len +size of the +.Fa iov +vector, +and, at last, +.Fa error +status of the transaction. +.Pp +.Fn ktrnamei +should be called every time a +.Xr namei 9 +operation is performed over the +.Fa path +name. +.Pp +.Fn ktrpsig +should be called for each signal +.Fa sig +posted for the traced process. +The +.Fa action +taken is one of the +.Nm SIG_DFL , +.Nm SIG_IGN , +.Nm SIG_ERR +as described in the +.Xr sigaction 2 +document. +.Fa mask +is the current traced process' signal mask. +Signal-specific code and +.Em siginfo_t +structure as descibed in the +.Aq Pa sys/siginfo.h +are given in the +.Fa code +and +.Fa si +arguments respectively. +.Pp +.Fn ktrsyscall +should be called for each system call number +.Fa code +executed with arguments in +.Fa args +of total count of +.Fa argsize . +.Pp +.Fn ktrsysret +should be called for a return from each system call number +.Fa code +and error number of +.Fa error +as described in the +.Xr errno 2 +and a return value in +.Fa retval that is syscall dependent. +.Sh CODE REFERENCES +These process tracing facility is implemented in +.Pa sys/kern/kern_ktrace.c . +.Sh SEE ALSO +.Xr errno 2 , +.Xr ktrace 2 , +.Xr syscall 2 , +.Xr namei 9 , +.Xr syscall 9 +.Sh HISTORY +The process tracing facility first appeared in +.Bx 4.4 . +.Pp +The +.Nm ktrace +section manual page appeared in +.Ox 3.4 . diff --git a/share/man/man9/namei.9 b/share/man/man9/namei.9 index f9615dfd286..99d434a8e3e 100644 --- a/share/man/man9/namei.9 +++ b/share/man/man9/namei.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: namei.9,v 1.2 2003/07/24 09:31:41 jmc Exp $ +.\" $OpenBSD: namei.9,v 1.3 2003/07/24 20:15:45 mickey Exp $ .\" $NetBSD: namei.9,v 1.9 2003/05/06 10:46:44 jmmv Exp $ .\" .\" Copyright (c) 2001 The NetBSD Foundation, Inc. @@ -116,13 +116,13 @@ structure This structure describes the subset of information from the nameidata structure that is passed through to the vnode operations. See -.Xr VOP_LOOKUP 9 +.Xr vnodeops 9 for more information. The details of the componentname structure are not absolutely necessary since the members are initialised by the helper macro .Fn NDINIT . It is useful to know the operations and flags as specified in -.Xr VOP_LOOKUP 9 . +.Xr vnodeops 9 . .Pp The .Nm @@ -295,9 +295,9 @@ The name lookup subsystem is implemented within the file .Sh SEE ALSO .Xr intro 9 , .\" .Xr namecache 9 , -.\" .Xr vfs 9 , +.Xr vfs 9 , .Xr vnode 9 -.\" .Xr vnodeops 9 +.Xr vnodeops 9 .Sh BUGS It is unfortunate that much of the .Nm diff --git a/share/man/man9/syscall.9 b/share/man/man9/syscall.9 new file mode 100644 index 00000000000..726a586e9e9 --- /dev/null +++ b/share/man/man9/syscall.9 @@ -0,0 +1,253 @@ +.\" $OpenBSD: syscall.9,v 1.1 2003/07/24 20:15:45 mickey Exp $ +.\" +.\" Copyright (c) 2003 Michael Shalayeff +.\" +.\" 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 REGENTS 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 REGENTS 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 MIND, 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 July 21, 2003 +.Dt SYSCALL 9 +.Os +.Sh NAME +.Nm syscall +.Nd "system calls overview" +.Sh DESCRIPTION +System calls in the kernel are implemented through a set of +switch tables for each emulation type. +Each table is generated from the +.Dq master +file by the +.Pa sys/kern/makesyscalls.sh +through the appropriate rules in the +.Pa Makefile . +.Pp +The +.Dq master +file is a text file sonsisting of a list of lines for each +system call. Lines may be split by the means of back slashing the end +of the line. +Each line is a set of fields seprated by whitespaces: +.Pp +.Cd number type ... +.Pp +Where: +.Bl -tag -width number -compact +.It number +is the system call number; +.It type +is one of: +.Bl -tag -width COMPAT_XXX -compact +.It STD +always included; +.It OBSOL +obsolete, not included in the system; +.It UNIMPL +unimplemented, not included in the system; +.It NODEF +included, but don't define the syscall number; +.It NOARGS +included, but don't define the syscall args structure; +.It INDIR +included, but don't define the syscall args structure, +and allow it to be "really" varargs; +.It COMPAT_XX +a compatibility systen call, only included if the corresponding +option is configured for the kernel (see +.Xr options 4 ). +.El +.El +.Pp +The rest of the line for the STD, NODEF, NOARGS, and COMPAT_XX +types is: +.Pp +.Cd { pseudo-proto } [alias] +.Pp +The +.Nm pseudo-proto +is a C-like prototype used to generate the system call argument list +and alias is an optional name alias for the call. +The function in the prototype has to be defined somewhere in +the kernel sources as it will be used as an entry point for +the corresponding system call. +.Pp +For other types the rest of the line is a comment. +.Pp +To generate the header and code files from the +.Dq master +file a +.Xr make 1 +command has to be ran from the directory containing the +.Dq master +file. +.Pp +.Ss Usage +Entry from the user space for the system call is machine dependant. +Typical code to invoke a system call from the machine dependant +sources might look like this: +.Bd -literal -offset indent + + const struct sysent *callp; + register_t code, args[8], rval[2]; + struct proc *p = curproc; + int code, nsys; + +\&... + +/* ``code'' is the system call number passed from the user space */ + +\&... + +if (code < 0 || code >= nsys) + callp += p->p_emul->e_nosys; /* illegal */ +else + callp += code; + +/* copyin the arguments from the user space */ +\&... + +#ifdef SYSCALL_DEBUG + scdebug_call(p, code, args); +#endif +#ifdef KTRACE + if (KTRPOINT(p, KTR_SYSCALL)) + ktrsyscall(p, code, argsize, args); +#endif + rval[0] = 0; +#if NSYSTRACE > 0 + if (ISSET(p->p_flag, P_SYSTRACE)) + error = systrace_redirect(code, p, args, rval); + else +#endif + error = (*callp->sy_call)(p, args, rval); + switch (error) { + case 0: + /* normal return */ + \&... + break; + case ERESTART: + /* + * adjust PC to point before the system call + * in the user space in order for the return + * back there we reenter the kernel to repeat + * the same system call + */ + \&... + break; + case EJUSTRETURN: + /* just return */ + break; + default: + /* + * an error returned: + * call an optional emulation errno mapping + * routine and return back to the user. + */ + if (p->p_emul->e_errno) + error = p->p_emul->e_errno[error]; + \&... + break; + } +#ifdef SYSCALL_DEBUG + scdebug_ret(p, code, orig_error, rval); +#endif + userret(p, frame.tf_eip, sticks); +#ifdef KTRACE + if (KTRPOINT(p, KTR_SYSRET)) + ktrsysret(p, code, orig_error, rval[0]); +#endif + +.Ed +.Pp +The +.Dq SYSCALL_DEBUG +parts of the code are explained in the section +.Dq Debugging +later in the document. +For the +.Dq KTRACE +portitions of the code refer to the +.Xr ktrace 9 +document for futher exlanations. +The +.Dq NSYSTRACE +is a system call tracing facility and is explained in the +.Xr systrace 9 +and +.Xr systrcae 4 +documents. +.Ss Debugging +For debugging purposes a line +.Pp +.Cd option SYSCALL_DEBUG +.Pp +should be inluded into the kernel configuration file (see +.Xr options 4 ). +This allows tracing for calls, returns, and arguments for both +implemented and not system calls. +A global integer variable +.Dr scdebug +contains a mask for for the desired logging events: +.Bl -tag -width SCDEBUG_SHOWARGS__ -compat +.It SCDEBUG_CALLS +(0x0001) show calls; +.It SCDEBUG_RETURNS +(0x0002) show returns; +.It SCDEBUG_ALL +(0x0004) show even syscalls that are implemented; +.It SCDEBUG_SHOWARGS +(0x0008) show arguments to calls. +.El +.Pp +Use +.Xr ddb 4 +to set the +.Dq scdebug +to a value desired. +.Sh CODE REFERENCES +.Bl -tag -width sys/kern/syscalls.master -compact +.It Pa sys/kern/makesyscalls.sh +a +.Xr sh 1 +script for generating C files out of the syscall master file; +.It Pa sys/{kern,compat/*}/syscalls.conf +a configuration file for the shell script above; +.It Pa sys/{kern,compat/*}/syscalls.master +master files describing names and numbers for the system calls; +.It Pa sys/{kern/,compat/*/*_}syscalls.c +system call names lists; +.It Pa sys/{kern/init,compat/*/*}_sysent.c +system call switch tables; +.It Pa sys/{sys/,compat/*/*_}syscallargs.h +system call argument lists; +.It Pa sys/{sys/,compat/*/*_}syscall.h +system call numbers. +.El +.Sh SEE ALSO +.Xr ktrace 2 , +.Xr syscall 2 , +.Xr systrace 4 , +.Xr ktrace 9 , +.Xr systrace 9 +.Sh HISTORY +The +.Nm +section manual page appeared in +.Ox 3.4 . diff --git a/share/man/man9/systrace.9 b/share/man/man9/systrace.9 new file mode 100644 index 00000000000..77275036188 --- /dev/null +++ b/share/man/man9/systrace.9 @@ -0,0 +1,89 @@ +.\" $OpenBSD: systrace.9,v 1.1 2003/07/24 20:15:45 mickey Exp $ +.\" +.\" Copyright (c) 2003 Michael Shalayeff +.\" +.\" 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 REGENTS 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 REGENTS 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 July 21, 2003 +.Dt INTRO 9 +.Os +.Sh NAME +.Nm systrace_redirect , +.Nm systrace_fork , +.Nm systrace_exit +.Nd "enforce policies for system calls" +.Sh SYNOPSIS +.In sys/dev/systrace.h +.Ft int +.Fn systrace_redirect "int code" "struct proc *p" "void *args" "register_t *retval" +.Ft void +.Fn systrace_fork "struct proc *oldproc" "struct proc *p" +.Ft void +.Fn systrace_exit "struct proc *p" +.Sh DESCRIPTION +These functions are used to enforce policy on the system calls as described in +.Xr systrace 1 . +.Pp +.Fn systrace_redirect +should be used to perform a system call number +.Fa code +with arguments +.Fa args +for the process +.Fa p . +Result is then put into the +.Fa retval +pointer. +Typycal code sequence would be: +.Bd -literal -offset indent +#include "systrace.h" + +\&... + +#if NSYSTRACE > 0 + if (ISSET(p->p_flag, P_SYSTRACE)) + error = systrace_redirect(code, p, args, rval); + else +#endif + error = (*callp->sy_call)(p, args, rval); +.Ed +.Pp +.Fn systrace_fork +is called from the +.Xr fork1 9 +function to inherit policy for the child process. +.Pp +.Fn systrace_exit +is called during the death cycle of the prcess to +detach the policy from the exiting process. +.Sh CODE REFERENCES +A subsystem for enforcing system call policies is implemented in +.Pa sys/dev/systrace.c . +.Sh SEE ALSO +.Xr systrace 1 , +.Xr systrace 4 , +.Xr syscall 9 +.Sh HISTORY +The +.Nm +section manual page appeared in +.Ox 3.4 . diff --git a/share/man/man9/vfs.9 b/share/man/man9/vfs.9 new file mode 100644 index 00000000000..a5fb841bddb --- /dev/null +++ b/share/man/man9/vfs.9 @@ -0,0 +1,64 @@ +.\" $OpenBSD: vfs.9,v 1.1 2003/07/24 20:15:45 mickey Exp $ +.\" $NetBSD: vfs.9,v 1.7 2003/02/25 10:35:34 wiz Exp $ +.\" +.\" Copyright (c) 2001 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 September 22, 2001 +.Dt VFS 9 +.Os +.Sh NAME +.Nm vfs +.Nd kernel interface to file systems +.Sh DESCRIPTION +The virtual file system, +.Nm VFS , +is the kernel interface to file systems. +The interface specifies the calls for the kernel to access file systems. +It also specifies the core functionality that a file system must provide +to the kernel. +.Pp +The focus of +.Nm +activity is the +.Em vnode +and is discussed in +.Xr vnode 9 . +.\" File system operations such as mounting and syncing are discussed in +.\" .Xr vfsops 9 . +.Sh SEE ALSO +.Xr intro 9 , +.\" .Xr vfsops 9 , +.Xr vnode 9 , +.Xr vnodeops 9 diff --git a/share/man/man9/vnodeops.9 b/share/man/man9/vnodeops.9 new file mode 100644 index 00000000000..4b86b318442 --- /dev/null +++ b/share/man/man9/vnodeops.9 @@ -0,0 +1,435 @@ +.\" $OpenBSD: vnodeops.9,v 1.1 2003/07/24 20:15:45 mickey 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 9 +.Os +.Sh NAME +.Nm VOP functions +.Nd vnode operations +.Sh SYNOPSIS +.Fd #include +.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 . -- cgit v1.2.3-59-g8ed1b