1.\" $NetBSD: fileassoc.9,v 1.25 2010/01/27 06:50:40 wiz 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 January 26, 2010 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.Ft int 37.Fn fileassoc_register "const char *name" \ 38"fileassoc_cleanup_cb_t cleanup_cb" "fileassoc_t *result" 39.Ft int 40.Fn fileassoc_deregister "fileassoc_t id" 41.Ft void * 42.Fn fileassoc_lookup "struct vnode *vp" "fileassoc_t id" 43.Ft int 44.Fn fileassoc_table_delete "struct mount *mp" 45.Ft int 46.Fn fileassoc_table_clear "struct mount *mp" "fileassoc_t id" 47.Ft int 48.Fn fileassoc_table_run "struct mount *mp" "fileassoc_t id" \ 49"fileassoc_cb_t cb" "void *cookie" 50.Ft int 51.Fn fileassoc_file_delete "struct vnode *vp" 52.Ft int 53.Fn fileassoc_add "struct vnode *vp" "fileassoc_t id" "void *data" 54.Ft int 55.Fn fileassoc_clear "struct vnode *vp" "fileassoc_t id" 56.Sh DESCRIPTION 57The 58.Nm 59KPI allows association of meta-data with files independent of file-system 60support for such elaborate meta-data. 61.Pp 62When plugging a new fileassoc to the system, a developer can specify private 63data to be associated with every file, as well as (potentially different) 64private data to be associated with every file-system mount. 65.Pp 66For example, a developer might choose to associate a custom ACL with every 67file, and a count of total files with ACLs with the mount. 68.Sh KERNEL PROGRAMMING INTERFACE 69Designed with simplicity in mind, the 70.Nm 71KPI usually accepts four different types of parameters to the most commonly 72used routines: 73.Bl -tag -width "123456" 74.It Ft struct mount * Ar mp 75Describing a mount on which to take action. 76.It Ft struct vnode * Ar vp 77Describing a file on which to take action. 78.It Ft fileassoc_t Ar id 79Describing an id, as returned from a successful call to 80.Fn fileassoc_register . 81.It Ft void * Ar data 82Describing a custom private data block, attached to either a file or a mount. 83.El 84.Pp 85Before using the 86.Nm 87KPI it is important to keep in mind that the interface provides memory 88management only for 89.Nm 90internal memory. 91Any additional memory stored in the tables (such as private data-structures 92used by custom fileassocs) should be allocated and freed by the developer. 93.Pp 94.Nm 95provides the ability to specify a 96.Dq cleanup 97routine to 98.Fn fileassoc_register 99(see below) 100to be called whenever an entry for a file or a mount is deleted. 101.Ss REGISTRATION AND DEREGISTRATION ROUTINES 102These routines allow a developer to allocate a 103.Nm 104slot to be used for private data. 105.Bl -tag -width "123456" 106.It Fn fileassoc_register "name" "cleanup_cb" "result" 107Registers a new fileassoc as 108.Ar name , 109and returns a 110.Ft fileassoc_t 111via 112.Fa result 113to be used as identifier in subsequent calls to the 114.Nm 115subsystem. 116.Pp 117.Fn fileassoc_register 118returns zero on success. 119Otherwise, an error number will be returned. 120.Pp 121If 122.Ar cleanup_cb 123is not 124.Dv NULL , 125it will be called during delete/clear operations (see routines below) with 126indication whether the passed data is file- or mount-specific. 127.Pp 128.Ar cleanup_cb 129should be a function receiving a 130.Ft void * 131and returning 132.Ft void . 133See the 134.Sx EXAMPLES 135section for illustration. 136.Pp 137.It Fn fileassoc_deregister "id" 138Deregisters a 139.Nm fileassoc 140whose id is 141.Ar id . 142.Pp 143Note that calling 144.Fn fileassoc_deregister 145only frees the associated slot in the 146.Nm 147subsystem. 148It is up to the developer to take care of garbage collection. 149.El 150.Ss LOOKUP ROUTINES 151These routines allow lookup of 152.Nm 153mounts, files, and private data attached to them. 154.Bl -tag -width "123456" 155.It Fn fileassoc_lookup "vp" "id" 156Returns the private data for the file/id combination 157or 158.Dv NULL 159if not found. 160.El 161.Ss MOUNT-WIDE ROUTINES 162.Bl -tag -width "123456" 163.It Fn fileassoc_table_delete "mp" 164Deletes a fileassoc table for 165.Ar mp . 166.Pp 167.It Fn fileassoc_table_clear "mp" "id" 168Clear all table entries for 169.Ar fileassoc 170from 171.Ar mp . 172.Pp 173If specified, the fileassoc's 174.Dq cleanup routine 175will be called with a pointer to the private data-structure. 176.Pp 177.It Fn fileassoc_table_run "mp" "id" "cb" "cookie" 178For each entry for 179.Ar id , 180call 181.Ar cb 182with the entry being the first argument, and 183.Ar cookie 184being the second argument. 185.Pp 186.Ar cb 187is a function returning 188.Ft void 189and receiving one 190.Ft "void *" 191parameter. 192.El 193.Ss FILE-SPECIFIC ROUTINES 194.Bl -tag -width "123456" 195.It Fn fileassoc_file_delete "vp" 196Delete the fileassoc entries for 197.Ar vp . 198.Pp 199If specified, the 200.Dq cleanup routines 201of all fileassoc types added will be called with a pointer to the corresponding 202private data structure and indication of 203.Dv FILEASSOC_CLEANUP_FILE . 204.El 205.Ss FILEASSOC-SPECIFIC ROUTINES 206.Bl -tag -width "123456" 207.It Fn fileassoc_add "vp" "id" "data" 208Add private data in 209.Ar data 210for 211.Ar vp , 212for the fileassoc specified by 213.Ar id . 214.Pp 215If a table for the mount-point 216.Ar vp 217is on doesn't exist, one will be created automatically. 218.Nm 219manages internally the optimal table sizes as tables are modified. 220.It Fn fileassoc_clear "vp" "id" 221Clear the private data for 222.Ar vp , 223for the fileassoc specified by 224.Ar id . 225.Pp 226If specified, the fileassoc's 227.Dq cleanup routine 228will be called with a pointer to the private data-structure and indication of 229.Dv FILEASSOC_CLEANUP_FILE . 230.El 231.Sh EXAMPLES 232The following code examples should give you a clue on using 233.Nm 234for your purposes. 235.Pp 236First, we'll begin with registering a new id. 237We need to do that to save a slot for private data storage with each mount 238and/or file: 239.Bd -literal -offset indent 240fileassoc_t myhook_id; 241int error; 242 243error = fileassoc_register("my_hook", myhook_cleanup, \*[Am]myhook_id); 244if (error != 0) 245 ...handle error... 246.Ed 247.Pp 248In the above example we pass a 249.Fn myhook_cleanup 250routine. 251It could look something like this: 252.Bd -literal -offset indent 253void 254myhook_cleanup(void *data) 255{ 256 257 printf("Myhook: Removing entry for file.\en"); 258 ...handle file entry removal... 259 free(data, M_TEMP); 260} 261.Ed 262.Pp 263Another useful thing would be to add our private data to a file. 264For example, let's assume we keep a custom ACL with each file: 265.Bd -literal -offset indent 266int 267myhook_acl_add(struct vnode *vp, struct myhook_acl *acl) 268{ 269 int error; 270 271 error = fileassoc_add(vp, myhook_id, acl); 272 if (error) { 273 printf("Myhook: Could not add ACL.\en"); 274 ...handle error... 275 } 276 277 printf("Myhook: Added ACL.\en"); 278 279 return (0); 280} 281.Ed 282.Pp 283Adding an entry will override any entry that previously exists. 284.Pp 285Whatever your plug is, eventually you'll want to access the private data you 286store with each file. 287To do that you can use the following: 288.Bd -literal -offset indent 289int 290myhook_acl_access(struct vnode *vp, int access_flags) 291{ 292 struct myhook_acl *acl; 293 294 acl = fileassoc_lookup(vp, myhook_id); 295 if (acl == NULL) 296 return (0); 297 298 error = myhook_acl_eval(acl, access_flags); 299 if (error) { 300 printf("Myhook: Denying access based on ACL decision.\en"); 301 return (error); 302 } 303 304 return (0); 305} 306.Ed 307.Pp 308And, in some cases, it may be desired to remove private data associated with 309an file: 310.Bd -literal -offset indent 311int error; 312 313error = fileassoc_clear(vp, myhook_id); 314if (error) { 315 printf("Myhook: Error occurred during fileassoc removal.\en"); 316 ...handle error... 317} 318.Ed 319.Pp 320As mentioned previously, the call to 321.Fn fileassoc_clear 322will result in a call to the 323.Dq cleanup routine 324specified in the initial call to 325.Fn fileassoc_register . 326.Pp 327The above should be enough to get you started. 328.Pp 329For example usage of 330.Nm , 331see the Veriexec code. 332.Sh CODE REFERENCES 333The 334.Nm 335is implemented within 336.Pa src/sys/kern/kern_fileassoc.c . 337.Sh HISTORY 338The 339.Nm 340KPI first appeared in 341.Nx 4.0 . 342.Sh AUTHORS 343.An Elad Efrat Aq elad@NetBSD.org 344.An Brett Lymn Aq blymn@NetBSD.org 345