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