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