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.\" %sccs.include.redist.roff% 10.\" 11.\" @(#)mount_null.8 8.4 (Berkeley) 04/19/94 12.\" 13.\" 14.Dd 15.Dt MOUNT_NULL 8 16.Os BSD 4.4 17.Sh NAME 18.Nm mount_null 19.Nd demonstrate the use of a null file system layer 20.Sh SYNOPSIS 21.Nm mount_null 22.Op Fl o Ar options 23.Ar target 24.Ar mount-point 25.Sh DESCRIPTION 26The 27.Nm mount_null 28command creates a 29null layer, duplicating a sub-tree of the file system 30name space under another part of the global file system namespace. 31In this respect, it is 32similar to the loopback file system (see 33.Xr mount_lofs 8 ) . 34It differs from 35the loopback file system in two respects: it is implemented using 36a stackable layers techniques, and it's 37.Do 38null-node 39.Dc s 40stack above 41all lower-layer vnodes, not just over directory vnodes. 42.Pp 43The options are as follows: 44.Bl -tag -width indent 45.It Fl o 46Options are specified with a 47.Fl o 48flag followed by a comma separated string of options. 49See the 50.Xr mount 8 51man page for possible options and their meanings. 52.El 53.Pp 54The null layer has two purposes. 55First, it serves as a demonstration of layering by proving a layer 56which does nothing. 57(It actually does everything the loopback file system does, 58which is slightly more than nothing.) 59Second, the null layer can serve as a prototype layer. 60Since it provides all necessary layer framework, 61new file system layers can be created very easily be starting 62with a null layer. 63.Pp 64The remainder of this man page examines the null layer as a basis 65for constructing new layers. 66.\" 67.\" 68.Sh INSTANTIATING NEW NULL LAYERS 69New null layers are created with 70.Xr mount_null 8 . 71.Xr Mount_null 8 72takes two arguments, the pathname 73of the lower vfs (target-pn) and the pathname where the null 74layer will appear in the namespace (mount-point-pn). After 75the null layer is put into place, the contents 76of target-pn subtree will be aliased under mount-point-pn. 77.\" 78.\" 79.Sh OPERATION OF A NULL LAYER 80The null layer is the minimum file system layer, 81simply bypassing all possible operations to the lower layer 82for processing there. The majority of its activity centers 83on the bypass routine, though which nearly all vnode operations 84pass. 85.Pp 86The bypass routine accepts arbitrary vnode operations for 87handling by the lower layer. It begins by examing vnode 88operation arguments and replacing any null-nodes by their 89lower-layer equivalents. It then invokes the operation 90on the lower layer. Finally, it replaces the null-nodes 91in the arguments and, if a vnode is returned by the operation, 92stacks a null-node on top of the returned vnode. 93.Pp 94Although bypass handles most operations, 95.Em vop_getattr , 96.Em vop_inactive , 97.Em vop_reclaim , 98and 99.Em vop_print 100are not bypassed. 101.Em Vop_getattr 102must change the fsid being returned. 103.Em Vop_inactive 104and vop_reclaim are not bypassed so that 105they can handle freeing null-layer specific data. 106.Em Vop_print 107is not bypassed to avoid excessive debugging 108information. 109.\" 110.\" 111.Sh INSTANTIATING VNODE STACKS 112Mounting associates the null layer with a lower layer, 113in effect stacking two VFSes. Vnode stacks are instead 114created on demand as files are accessed. 115.Pp 116The initial mount creates a single vnode stack for the 117root of the new null layer. All other vnode stacks 118are created as a result of vnode operations on 119this or other null vnode stacks. 120.Pp 121New vnode stacks come into existence as a result of 122an operation which returns a vnode. 123The bypass routine stacks a null-node above the new 124vnode before returning it to the caller. 125.Pp 126For example, imagine mounting a null layer with 127.Bd -literal -offset indent 128mount_null /usr/include /dev/layer/null 129.Ed 130Changing directory to 131.Pa /dev/layer/null 132will assign 133the root null-node (which was created when the null layer was mounted). 134Now consider opening 135.Pa sys . 136A vop_lookup would be 137done on the root null-node. This operation would bypass through 138to the lower layer which would return a vnode representing 139the UFS 140.Pa sys . 141Null_bypass then builds a null-node 142aliasing the UFS 143.Pa sys 144and returns this to the caller. 145Later operations on the null-node 146.Pa sys 147will repeat this 148process when constructing other vnode stacks. 149.\" 150.\" 151.Sh CREATING OTHER FILE SYSTEM LAYERS 152One of the easiest ways to construct new file system layers is to make 153a copy of the null layer, rename all files and variables, and 154then begin modifyng the copy. Sed can be used to easily rename 155all variables. 156.Pp 157The umap layer is an example of a layer descended from the 158null layer. 159.\" 160.\" 161.Sh INVOKING OPERATIONS ON LOWER LAYERS 162There are two techniques to invoke operations on a lower layer 163when the operation cannot be completely bypassed. Each method 164is appropriate in different situations. In both cases, 165it is the responsibility of the aliasing layer to make 166the operation arguments "correct" for the lower layer 167by mapping an vnode arguments to the lower layer. 168.Pp 169The first approach is to call the aliasing layer's bypass routine. 170This method is most suitable when you wish to invoke the operation 171currently being handled on the lower layer. It has the advantage 172the the bypass routine already must do argument mapping. 173An example of this is 174.Em null_getattrs 175in the null layer. 176.Pp 177A second approach is to directly invoked vnode operations on 178the lower layer with the 179.Em VOP_OPERATIONNAME 180interface. 181The advantage of this method is that it is easy to invoke 182arbitrary operations on the lower layer. The disadvantage 183is that vnodes arguments must be manually mapped. 184.\" 185.\" 186.Sh SEE ALSO 187.Xr mount 8 188.sp 189UCLA Technical Report CSD-910056, 190.Em "Stackable Layers: an Architecture for File System Development" . 191.Sh HISTORY 192The 193.Nm mount_null 194utility first appeared in 4.4BSD. 195