sbin/mount_null/mount_null.8

   1 .\"
   2 .\" Copyright (c) 1992, 1993, 1994
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\"
   5 .\" This code is derived from software donated to Berkeley by
   6 .\" John Heidemann of the UCLA Ficus project.
   7 .\"
   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 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\"
  37 .\"     @(#)mount_null.8        8.6 (Berkeley) 5/1/95
  38 .\" $FreeBSD: src/sbin/mount_null/mount_null.8,v 1.11.2.6 2001/12/20 16:40:00 ru Exp $
  39 .\"
  40 .Dd May 1, 1995
  41 .Dt MOUNT_NULL 8
  42 .Os
  43 .Sh NAME
  44 .Nm mount_null
  45 .Nd "mount a loopback filesystem sub-tree; demonstrate the use of a null file system layer"
  46 .Sh SYNOPSIS
  47 .Nm
  48 .Op Fl o Ar options
  49 .Ar target
  50 .Ar mount-point
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 command creates a
  55 null layer, duplicating a sub-tree of the file system
  56 name space under another part of the global file system namespace.
  57 This allows existing files and directories to be accessed
  58 using a different pathname.
  59 .Pp
  60 The primary differences between a virtual copy of the filesystem
  61 and a symbolic link are that the
  62 .Xr getcwd 3
  63 functions work correctly in the virtual copy, and that other filesystems
  64 may be mounted on the virtual copy without affecting the original.
  65 A different device number for the virtual copy is returned by
  66 .Xr stat 2 ,
  67 but in other respects it is indistinguishable from the original.
  68 .Pp
  69 The
  70 .Nm
  71 filesystem differs from a traditional
  72 loopback file system in two respects: it is implemented using
  73 a stackable layers techniques, and it's
  74 .Do null-node Dc Ns s
  75 stack above
  76 all lower-layer vnodes, not just over directory vnodes.
  77 .Pp
  78 The options are as follows:
  79 .Bl -tag -width indent
  80 .It Fl o
  81 Options are specified with a
  82 .Fl o
  83 flag followed by a comma separated string of options.
  84 See the
  85 .Xr mount 8
  86 man page for possible options and their meanings.
  87 .El
  88 .Pp
  89 The null layer has two purposes.
  90 First, it serves as a demonstration of layering by providing a layer
  91 which does nothing.
  92 (It actually does everything the loopback file system does,
  93 which is slightly more than nothing.)
  94 Second, the null layer can serve as a prototype layer.
  95 Since it provides all necessary layer framework,
  96 new file system layers can be created very easily by starting
  97 with a null layer.
  98 .Pp
  99 The remainder of this man page examines the null layer as a basis
 100 for constructing new layers.
 101 .\"
 102 .\"
 103 .Sh INSTANTIATING NEW NULL LAYERS
 104 New null layers are created with
 105 .Nm .
 106 .Nm Mount_null
 107 takes two arguments, the pathname
 108 of the lower vfs (target-pn) and the pathname where the null
 109 layer will appear in the namespace (mount-point-pn).  After
 110 the null layer is put into place, the contents
 111 of target-pn subtree will be aliased under mount-point-pn.
 112 .\"
 113 .\"
 114 .Sh OPERATION OF A NULL LAYER
 115 The null layer is the minimum file system layer,
 116 simply bypassing all possible operations to the lower layer
 117 for processing there.  The majority of its activity centers
 118 on the bypass routine, through which nearly all vnode operations
 119 pass.
 120 .Pp
 121 The bypass routine accepts arbitrary vnode operations for
 122 handling by the lower layer.  It begins by examining vnode
 123 operation arguments and replacing any null-nodes by their
 124 lower-layer equivalents.  It then invokes the operation
 125 on the lower layer.  Finally, it replaces the null-nodes
 126 in the arguments and, if a vnode is returned by the operation,
 127 stacks a null-node on top of the returned vnode.
 128 .Pp
 129 Although bypass handles most operations,
 130 .Em vop_getattr ,
 131 .Em vop_inactive ,
 132 .Em vop_reclaim ,
 133 and
 134 .Em vop_print
 135 are not bypassed.
 136 .Em Vop_getattr
 137 must change the fsid being returned.
 138 .Em Vop_inactive
 139 and
 140 .Em vop_reclaim
 141 are not bypassed so that
 142 they can handle freeing null-layer specific data.
 143 .Em Vop_print
 144 is not bypassed to avoid excessive debugging
 145 information.
 146 .\"
 147 .\"
 148 .Sh INSTANTIATING VNODE STACKS
 149 Mounting associates the null layer with a lower layer,
 150 in effect stacking two VFSes.  Vnode stacks are instead
 151 created on demand as files are accessed.
 152 .Pp
 153 The initial mount creates a single vnode stack for the
 154 root of the new null layer.  All other vnode stacks
 155 are created as a result of vnode operations on
 156 this or other null vnode stacks.
 157 .Pp
 158 New vnode stacks come into existence as a result of
 159 an operation which returns a vnode.
 160 The bypass routine stacks a null-node above the new
 161 vnode before returning it to the caller.
 162 .Pp
 163 For example, imagine mounting a null layer with
 164 .Bd -literal -offset indent
 165 mount_null /usr/include /dev/layer/null
 166 .Ed
 167 Changing directory to
 168 .Pa /dev/layer/null
 169 will assign
 170 the root null-node (which was created when the null layer was mounted).
 171 Now consider opening
 172 .Pa sys .
 173 A vop_lookup would be
 174 done on the root null-node.  This operation would bypass through
 175 to the lower layer which would return a vnode representing
 176 the UFS
 177 .Pa sys .
 178 Null_bypass then builds a null-node
 179 aliasing the UFS
 180 .Pa sys
 181 and returns this to the caller.
 182 Later operations on the null-node
 183 .Pa sys
 184 will repeat this
 185 process when constructing other vnode stacks.
 186 .\"
 187 .\"
 188 .Sh CREATING OTHER FILE SYSTEM LAYERS
 189 One of the easiest ways to construct new file system layers is to make
 190 a copy of the null layer, rename all files and variables, and
 191 then begin modifying the copy.
 192 .Xr Sed 1
 193 can be used to easily rename
 194 all variables.
 195 .Pp
 196 The umap layer is an example of a layer descended from the
 197 null layer.
 198 .\"
 199 .\"
 200 .Sh INVOKING OPERATIONS ON LOWER LAYERS
 201 There are two techniques to invoke operations on a lower layer
 202 when the operation cannot be completely bypassed.  Each method
 203 is appropriate in different situations.  In both cases,
 204 it is the responsibility of the aliasing layer to make
 205 the operation arguments "correct" for the lower layer
 206 by mapping a vnode argument to the lower layer.
 207 .Pp
 208 The first approach is to call the aliasing layer's bypass routine.
 209 This method is most suitable when you wish to invoke the operation
 210 currently being handled on the lower layer.
 211 It has the advantage that
 212 the bypass routine already must do argument mapping.
 213 An example of this is
 214 .Em null_getattrs
 215 in the null layer.
 216 .Pp
 217 A second approach is to directly invoke vnode operations on
 218 the lower layer with the
 219 .Em VOP_OPERATIONNAME
 220 interface.
 221 The advantage of this method is that it is easy to invoke
 222 arbitrary operations on the lower layer.  The disadvantage
 223 is that vnode arguments must be manually mapped.
 224 .\"
 225 .\"
 226 .Sh SEE ALSO
 227 .Xr mount 8
 228 .Pp
 229 UCLA Technical Report CSD-910056,
 230 .Em "Stackable Layers: an Architecture for File System Development" .
 231 .Sh BUGS
 232 THIS FILESYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK)
 233 AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM.  USE AT YOUR
 234 OWN RISK.  BEWARE OF DOG.  SLIPPERY WHEN WET.
 235 .Pp
 236 This code also needs an owner in order to be less dangerous - serious
 237 hackers can apply by sending mail to
 238 .Aq hackers@FreeBSD.org
 239 and announcing
 240 their intent to take it over.
 241 .Sh HISTORY
 242 The
 243 .Nm
 244 utility first appeared in
 245 .Bx 4.4 .