| blob | 58e66e7481733ad62be46eee14d26e83711f1990 |
1 .\" $NetBSD: fileassoc.9,v 1.21 2008/05/28 00:31:10 snj Exp $
2 .\"
3 .\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org>
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. The name of the author may not be used to endorse or promote products
15 .\" derived from this software without specific prior written permission.
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 .\"
28 .Dd May 15, 2007
29 .Dt FILEASSOC 9
30 .Os
31 .Sh NAME
32 .Nm fileassoc
33 .Nd in-kernel, file-system independent, file-meta data association
34 .Sh SYNOPSIS
35 .In sys/fileassoc.h
36 .Sh DESCRIPTION
37 The
38 .Nm
39 KPI allows association of meta-data with files independent of file-system
40 support for such elaborate meta-data.
41 .Pp
42 When plugging a new fileassoc to the system, a developer can specify private
43 data to be associated with every file, as well as (potentially different)
44 private data to be associated with every file-system mount.
45 .Pp
46 For example, a developer might choose to associate a custom ACL with every
47 file, and a count of total files with ACLs with the mount.
48 .Ss Kernel Programming Interface
49 Designed with simplicity in mind, the
50 .Nm
51 KPI usually accepts four different types of parameters to the most commonly
52 used routines:
53 .Bl -tag -width "123456"
54 .It Ft struct mount * Ar mp
55 Describing a mount on which to take action.
56 .It Ft struct vnode * Ar vp
57 Describing a file on which to take action.
58 .It Ft fileassoc_t Ar id
59 Describing an id, as returned from a successful call to
60 .Fn fileassoc_register .
61 .It Ft void * Ar data
62 Describing a custom private data block, attached to either a file or a mount.
63 .El
64 .Pp
65 Before using the
66 .Nm
67 KPI it is important to keep in mind that the interface provides memory
68 management only for
69 .Nm
70 internal memory.
71 Any additional memory stored in the tables (such as private data-structures
72 used by custom fileassocs) should be allocated and freed by the developer.
73 .Pp
74 .Nm
75 provides the ability to specify a
76 .Dq cleanup
77 routine to
78 .Fn fileassoc_register
79 (see below)
80 to be called whenever an entry for a file or a mount is deleted.
81 .Ss Fileassoc Registration and Deregistration Routines
82 These routines allow a developer to allocate a
83 .Nm
84 slot to be used for private data.
85 .Bl -tag -width "123456"
86 .It Ft int Fn fileassoc_register "const char *name" \
87 "fileassoc_cleanup_cb_t cleanup_cb" "fileassoc_t *result"
88 Registers a new fileassoc as
89 .Ar name ,
90 and returns a
91 .Ft fileassoc_t
92 via
93 .Fa result
94 to be used as identifier in subsequent calls to the
95 .Nm
96 subsystem.
97 .Pp
98 .Fn fileassoc_register
99 returns zero on success.
100 Otherwise, an error number will be returned.
101 .Pp
102 If
103 .Ar cleanup_cb
104 is not
105 .Dv NULL ,
106 it will be called during delete/clear operations (see routines below) with
107 indication whether the passed data is file- or mount-specific.
108 .Pp
109 .Ar cleanup_cb
110 should be a function receiving a
111 .Ft void *
112 and returning
113 .Ft void .
114 See the
115 .Sx EXAMPLES
116 section for illustration.
117 .Pp
118 .It Ft int Fn fileassoc_deregister "fileassoc_t id"
119 Deregisters a
120 .Nm fileassoc
121 whose id is
122 .Ar id .
123 .Pp
124 Note that calling
125 .Fn fileassoc_deregister
126 only frees the associated slot in the
127 .Nm
128 subsystem.
129 It is up to the developer to take care of garbage collection.
130 .El
131 .Ss Lookup Routines
132 These routines allow lookup of
133 .Nm
134 mounts, files, and private data attached to them.
135 .Bl -tag -width "123456"
136 .It Ft void * Fn fileassoc_lookup "struct vnode *vp" "fileassoc_t id"
137 Returns the private data for the file/id combination
138 or
139 .Dv NULL
140 if not found.
141 .El
142 .Ss Mount-wide Routines
143 .Bl -tag -width "123456"
144 .It Ft int Fn fileassoc_table_delete "struct mount *mp"
145 Deletes a fileassoc table for
146 .Ar mp .
147 .Pp
148 .It Ft int Fn fileassoc_table_clear "struct mount *mp" "fileassoc_t id"
149 Clear all table entries for
150 .Ar fileassoc
151 from
152 .Ar mp .
153 .Pp
154 If specified, the fileassoc's
155 .Dq cleanup routine
156 will be called with a pointer to the private data-structure.
157 .Pp
158 .It Ft int Fn fileassoc_table_run "struct mount *mp" "fileassoc_t id" \
159 "fileassoc_cb_t cb" "void *cookie"
160 For each entry for
161 .Ar id ,
162 call
163 .Ar cb
164 with the entry being the first argument, and
165 .Ar cookie
166 being the second argument.
167 .Pp
168 .Ar cb
169 is a function returning
170 .Ft void
171 and receiving one
172 .Ft "void *"
173 parameter.
174 .El
175 .Ss File-specific Routines
176 .Bl -tag -width "123456"
177 .It Ft int Fn fileassoc_file_delete "struct vnode *vp"
178 Delete the fileassoc entries for
179 .Ar vp .
180 .Pp
181 If specified, the
182 .Dq cleanup routines
183 of all fileassoc types added will be called with a pointer to the corresponding
184 private data structure and indication of
185 .Dv FILEASSOC_CLEANUP_FILE .
186 .El
187 .Ss Fileassoc-specific Routines
188 .Bl -tag -width "123456"
189 .It Ft int Fn fileassoc_add "struct vnode *vp" "fileassoc_t id" "void *data"
190 Add private data in
191 .Ar data
192 for
193 .Ar vp ,
194 for the fileassoc specified by
195 .Ar id .
196 .Pp
197 If a table for the mount-point
198 .Ar vp
199 is on doesn't exist, one will be created automatically.
200 .Nm
201 manages internally the optimal table sizes as tables are modified.
202 .It Ft int Fn fileassoc_clear "struct vnode *vp" "fileassoc_t id"
203 Clear the private data for
204 .Ar vp ,
205 for the fileassoc specified by
206 .Ar id .
207 .Pp
208 If specified, the fileassoc's
209 .Dq cleanup routine
210 will be called with a pointer to the private data-structure and indication of
211 .Dv FILEASSOC_CLEANUP_FILE .
212 .El
213 .Sh EXAMPLES
214 The following code examples should give you a clue on using
215 .Nm
216 for your purposes.
217 .Pp
218 First, we'll begin with registering a new id.
219 We need to do that to save a slot for private data storage with each mount
220 and/or file:
221 .Bd -literal -offset indent
222 fileassoc_t myhook_id;
223 int error;
225 error = fileassoc_register("my_hook", myhook_cleanup, \*[Am]myhook_id);
226 if (error != 0)
227 ...handle error...
228 .Ed
229 .Pp
230 In the above example we pass a
231 .Fn myhook_cleanup
232 routine.
233 It could look something like this:
234 .Bd -literal -offset indent
235 void
236 myhook_cleanup(void *data)
237 {
239 printf("Myhook: Removing entry for file.\en");
240 ...handle file entry removal...
241 free(data, M_TEMP);
242 }
243 .Ed
244 .Pp
245 Another useful thing would be to add our private data to a file.
246 For example, let's assume we keep a custom ACL with each file:
247 .Bd -literal -offset indent
248 int
249 myhook_acl_add(struct vnode *vp, struct myhook_acl *acl)
250 {
251 int error;
253 error = fileassoc_add(vp, myhook_id, acl);
254 if (error) {
255 printf("Myhook: Could not add ACL.\en");
256 ...handle error...
257 }
259 printf("Myhook: Added ACL.\en");
261 return (0);
262 }
263 .Ed
264 .Pp
265 Adding an entry will override any entry that previously exists.
266 .Pp
267 Whatever your plug is, eventually you'll want to access the private data you
268 store with each file.
269 To do that you can use the following:
270 .Bd -literal -offset indent
271 int
272 myhook_acl_access(struct vnode *vp, int access_flags)
273 {
274 struct myhook_acl *acl;
276 acl = fileassoc_lookup(vp, myhook_id);
277 if (acl == NULL)
278 return (0);
280 error = myhook_acl_eval(acl, access_flags);
281 if (error) {
282 printf("Myhook: Denying access based on ACL decision.\en");
283 return (error);
284 }
286 return (0);
287 }
288 .Ed
289 .Pp
290 And, in some cases, it may be desired to remove private data associated with
291 an file:
292 .Bd -literal -offset indent
293 int error;
295 error = fileassoc_clear(vp, myhook_id);
296 if (error) {
297 printf("Myhook: Error occurred during fileassoc removal.\en");
298 ...handle error...
299 }
300 .Ed
301 .Pp
302 As mentioned previously, the call to
303 .Fn fileassoc_clear
304 will result in a call to the
305 .Dq cleanup routine
306 specified in the initial call to
307 .Fn fileassoc_register .
308 .Pp
309 The above should be enough to get you started.
310 .Pp
311 For example usage of
312 .Nm ,
313 see the Veriexec code.
314 .Sh CODE REFERENCES
315 .Pa src/sys/kern/kern_fileassoc.c
316 .Sh HISTORY
317 The
318 .Nm
319 KPI first appeared in
320 .Nx 4.0 .
321 .Sh AUTHORS
322 .An Elad Efrat Aq elad@NetBSD.org
323 .An Brett Lymn Aq blymn@NetBSD.org