share/man/man9/vfs_hooks.9

   1 .\"     $NetBSD: vfs_hooks.9,v 1.3 2006/01/16 22:05:21 yamt Exp $
   2 .\"
   3 .\" Copyright (c) 2005 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Julio M. Merino Vidal.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd September 23, 2005
  31 .Dt VFS_HOOKS 9
  32 .Os
  33 .Sh NAME
  34 .Nm vfs_hooks ,
  35 .Nm vfs_hooks_unmount
  36 .Nd VFS hooks interface
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/mount.h
  40 .Ft void
  41 .Fn vfs_hooks_unmount "struct mount *mp"
  42 .Sh DESCRIPTION
  43 The VFS hooks interface provides a way for different kernel subsystems to
  44 attach custom functions to specific VFS operations.
  45 This enforces code separation by keeping the VFS's core sources uncluttered
  46 and makes all subsystem functionality reside in a single place.
  47 As an example, this interface is used by the NFS server code to automatically
  48 handle the exports list for each mount point.
  49 .Pp
  50 Hooks are described by a
  51 .Ft struct vfs_hooks
  52 object, as seen below:
  53 .Bd -literal
  54 struct vfs_hooks {
  55         int     (*vh_unmount)(struct mount *);
  56 };
  57 .Ed
  58 .Pp
  59 For simplicity, each field is named after the VFS operation it refers to.
  60 The purpose of each member function, alongside some important notes, is
  61 shown below:
  62 .Bl -tag -width compat
  63 .It Fn vh_unmount "mp"
  64 This hook is executed during the unmount process of a file system.
  65 .El
  66 .Pp
  67 For more information about the purpose of each operation, see
  68 .Xr vfsops 9 .
  69 Note that any of these fields may be a null pointer.
  70 .Pp
  71 After the definition of a
  72 .Ft struct vfs_hooks
  73 object, the kernel has to add it to the
  74 .Va vfs_hooks
  75 link set using the
  76 .Fn VFS_HOOKS_ATTACH "struct vfs_hooks *"
  77 macro.
  78 .Pp
  79 Please note that this interface is incomplete on purpose to keep it in its
  80 smallest possible size (i.e., do not provide a hook that is not used).
  81 If you feel the need to hook a routine to a VFS operation that is not yet
  82 supported by this interface, just add it to the files described in
  83 .Sx CODE REFERENCES .
  84 .Sh FUNCTIONS
  85 The following functions are provided to the VFS code to run the hooked
  86 functions:
  87 .Bl -tag -width compact
  88 .It Fn vfs_hooks_unmount "mp"
  89 Runs all hooks for the VFS unmount operation.
  90 Given that these operations shall not fail, it returns
  91 .Ft void .
  92 .El
  93 .Sh CODE REFERENCES
  94 The VFS hooks interface is implemented within the files
  95 .Pa sys/kern/vfs_hooks.c
  96 and
  97 .Pa sys/sys/mount.h .
  98 .Sh SEE ALSO
  99 .Xr intro 9 ,
 100 .Xr vfs 9 ,
 101 .Xr vfsops 9
 102 .Sh HISTORY
 103 The VFS hooks interface appeared in
 104 .Nx 4.0 .