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