diff options
Diffstat (limited to 'static/netbsd/man9/fileassoc.9 3.html')
| -rw-r--r-- | static/netbsd/man9/fileassoc.9 3.html | 338 |
1 files changed, 0 insertions, 338 deletions
diff --git a/static/netbsd/man9/fileassoc.9 3.html b/static/netbsd/man9/fileassoc.9 3.html deleted file mode 100644 index d4c28048..00000000 --- a/static/netbsd/man9/fileassoc.9 3.html +++ /dev/null @@ -1,338 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">FILEASSOC(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">FILEASSOC(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">fileassoc</code> — - <span class="Nd">in-kernel, file system independent, file meta-data - association</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/fileassoc.h</a>></code></p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">fileassoc_register</code>(<var class="Fa" style="white-space: nowrap;">const - char *name</var>, - <var class="Fa" style="white-space: nowrap;">fileassoc_cleanup_cb_t - cleanup_cb</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t - *result</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">fileassoc_deregister</code>(<var class="Fa" style="white-space: nowrap;">fileassoc_t - id</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">fileassoc_lookup</code>(<var class="Fa" style="white-space: nowrap;">struct - vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t - id</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">fileassoc_table_delete</code>(<var class="Fa" style="white-space: nowrap;">struct - mount *mp</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">fileassoc_table_clear</code>(<var class="Fa" style="white-space: nowrap;">struct - mount *mp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t - id</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">fileassoc_table_run</code>(<var class="Fa" style="white-space: nowrap;">struct - mount *mp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t - id</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_cb_t - cb</var>, <var class="Fa" style="white-space: nowrap;">void - *cookie</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">fileassoc_file_delete</code>(<var class="Fa" style="white-space: nowrap;">struct - vnode *vp</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">fileassoc_add</code>(<var class="Fa" style="white-space: nowrap;">struct - vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t - id</var>, <var class="Fa" style="white-space: nowrap;">void - *data</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">fileassoc_clear</code>(<var class="Fa" style="white-space: nowrap;">struct - vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t - id</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">fileassoc</code> KPI allows association of - meta-data with files independent of file system support for such elaborate - meta-data.</p> -<p class="Pp">When plugging a new fileassoc to the system, a developer can - specify private data to be associated with every file, as well as - (potentially different) private data to be associated with every file system - mount.</p> -<p class="Pp">For example, a developer might choose to associate a custom ACL - with every file, and a count of total files with ACLs with the mount.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="KERNEL_PROGRAMMING_INTERFACE"><a class="permalink" href="#KERNEL_PROGRAMMING_INTERFACE">KERNEL - PROGRAMMING INTERFACE</a></h1> -<p class="Pp">Designed with simplicity in mind, the - <code class="Nm">fileassoc</code> KPI usually accepts four different types - of parameters to the most commonly used routines:</p> -<dl class="Bl-tag"> - <dt><var class="Ft">struct mount *</var> <var class="Ar">mp</var></dt> - <dd>Describing a mount on which to take action.</dd> - <dt><var class="Ft">struct vnode *</var> <var class="Ar">vp</var></dt> - <dd>Describing a file on which to take action.</dd> - <dt id="fileassoc_register"><var class="Ft">fileassoc_t</var> - <var class="Ar">id</var></dt> - <dd>Describing an id, as returned from a successful call to - <a class="permalink" href="#fileassoc_register"><code class="Fn">fileassoc_register</code></a>().</dd> - <dt><var class="Ft">void *</var> <var class="Ar">data</var></dt> - <dd>Describing a custom private data block, attached to either a file or a - mount.</dd> -</dl> -<p class="Pp">Before using the <code class="Nm">fileassoc</code> KPI it is - important to keep in mind that the interface provides memory management only - for <code class="Nm">fileassoc</code> internal memory. Any additional memory - stored in the tables (such as private data structures used by custom - fileassocs) should be allocated and freed by the developer.</p> -<p class="Pp" id="fileassoc_register~2"><code class="Nm">fileassoc</code> - provides the ability to specify a “cleanup” routine to - <a class="permalink" href="#fileassoc_register~2"><code class="Fn">fileassoc_register</code></a>() - (see below) to be called whenever an entry for a file or a mount is - deleted.</p> -<section class="Ss"> -<h2 class="Ss" id="REGISTRATION_AND_DEREGISTRATION_ROUTINES"><a class="permalink" href="#REGISTRATION_AND_DEREGISTRATION_ROUTINES">REGISTRATION - AND DEREGISTRATION ROUTINES</a></h2> -<p class="Pp">These routines allow a developer to allocate a - <code class="Nm">fileassoc</code> slot to be used for private data.</p> -<dl class="Bl-tag"> - <dt><code class="Fn">fileassoc_register</code>(<var class="Fa">name</var>, - <var class="Fa">cleanup_cb</var>, <var class="Fa">result</var>)</dt> - <dd>Registers a new fileassoc as <var class="Ar">name</var>, and returns a - <var class="Ft">fileassoc_t</var> via <var class="Fa">result</var> to be - used as identifier in subsequent calls to the - <code class="Nm">fileassoc</code> subsystem. - <p class="Pp" id="fileassoc_register~3"><a class="permalink" href="#fileassoc_register~3"><code class="Fn">fileassoc_register</code></a>() - returns zero on success. Otherwise, an error number will be - returned.</p> - <p class="Pp">If <var class="Ar">cleanup_cb</var> is not - <code class="Dv">NULL</code>, it will be called during delete/clear - operations (see routines below) with indication whether the passed data - is file- or mount-specific.</p> - <p class="Pp"><var class="Ar">cleanup_cb</var> should be a function - receiving a <var class="Ft">void *</var> and returning - <var class="Ft">void</var>. See the - <a class="Sx" href="#EXAMPLES">EXAMPLES</a> section for - illustration.</p> - </dd> - <dt id="fileassoc_deregister"><a class="permalink" href="#fileassoc_deregister"><code class="Fn">fileassoc_deregister</code></a>(<var class="Fa">id</var>)</dt> - <dd>Deregisters a <code class="Nm">fileassoc</code> whose id is - <var class="Ar">id</var>. - <p class="Pp" id="fileassoc_deregister~2">Note that calling - <a class="permalink" href="#fileassoc_deregister~2"><code class="Fn">fileassoc_deregister</code></a>() - only frees the associated slot in the <code class="Nm">fileassoc</code> - subsystem. It is up to the developer to take care of garbage - collection.</p> - </dd> -</dl> -</section> -<section class="Ss"> -<h2 class="Ss" id="LOOKUP_ROUTINES"><a class="permalink" href="#LOOKUP_ROUTINES">LOOKUP - ROUTINES</a></h2> -<p class="Pp">These routines allow lookup of <code class="Nm">fileassoc</code> - mounts, files, and private data attached to them.</p> -<dl class="Bl-tag"> - <dt id="fileassoc_lookup"><a class="permalink" href="#fileassoc_lookup"><code class="Fn">fileassoc_lookup</code></a>(<var class="Fa">vp</var>, - <var class="Fa">id</var>)</dt> - <dd>Returns the private data for the file/id combination or - <code class="Dv">NULL</code> if not found.</dd> -</dl> -</section> -<section class="Ss"> -<h2 class="Ss" id="MOUNT-WIDE_ROUTINES"><a class="permalink" href="#MOUNT-WIDE_ROUTINES">MOUNT-WIDE - ROUTINES</a></h2> -<dl class="Bl-tag"> - <dt id="fileassoc_table_delete"><a class="permalink" href="#fileassoc_table_delete"><code class="Fn">fileassoc_table_delete</code></a>(<var class="Fa">mp</var>)</dt> - <dd>Deletes a fileassoc table for <var class="Ar">mp</var>.</dd> - <dt id="fileassoc_table_clear"><a class="permalink" href="#fileassoc_table_clear"><code class="Fn">fileassoc_table_clear</code></a>(<var class="Fa">mp</var>, - <var class="Fa">id</var>)</dt> - <dd>Clear all table entries for <var class="Ar">fileassoc</var> from - <var class="Ar">mp</var>. - <p class="Pp">If specified, the fileassoc's “cleanup routine” - will be called with a pointer to the private data structure.</p> - </dd> - <dt id="fileassoc_table_run"><a class="permalink" href="#fileassoc_table_run"><code class="Fn">fileassoc_table_run</code></a>(<var class="Fa">mp</var>, - <var class="Fa">id</var>, <var class="Fa">cb</var>, - <var class="Fa">cookie</var>)</dt> - <dd>For each entry for <var class="Ar">id</var>, call <var class="Ar">cb</var> - with the entry being the first argument, and <var class="Ar">cookie</var> - being the second argument. - <p class="Pp"><var class="Ar">cb</var> is a function returning - <var class="Ft">void</var> and receiving two <var class="Ft">void - *</var> parameters.</p> - </dd> -</dl> -</section> -<section class="Ss"> -<h2 class="Ss" id="FILE-SPECIFIC_ROUTINES"><a class="permalink" href="#FILE-SPECIFIC_ROUTINES">FILE-SPECIFIC - ROUTINES</a></h2> -<dl class="Bl-tag"> - <dt id="fileassoc_file_delete"><a class="permalink" href="#fileassoc_file_delete"><code class="Fn">fileassoc_file_delete</code></a>(<var class="Fa">vp</var>)</dt> - <dd>Delete the fileassoc entries for <var class="Ar">vp</var>. - <p class="Pp">If specified, the “cleanup routines” of all - fileassoc types added will be called with a pointer to the corresponding - private data structure and indication of - <code class="Dv">FILEASSOC_CLEANUP_FILE</code>.</p> - </dd> -</dl> -</section> -<section class="Ss"> -<h2 class="Ss" id="FILEASSOC-SPECIFIC_ROUTINES"><a class="permalink" href="#FILEASSOC-SPECIFIC_ROUTINES">FILEASSOC-SPECIFIC - ROUTINES</a></h2> -<dl class="Bl-tag"> - <dt id="fileassoc_add"><a class="permalink" href="#fileassoc_add"><code class="Fn">fileassoc_add</code></a>(<var class="Fa">vp</var>, - <var class="Fa">id</var>, <var class="Fa">data</var>)</dt> - <dd>Add private data in <var class="Ar">data</var> for - <var class="Ar">vp</var>, for the fileassoc specified by - <var class="Ar">id</var>. - <p class="Pp">If a table for the mount-point <var class="Ar">vp</var> is on - doesn't exist, one will be created automatically. - <code class="Nm">fileassoc</code> manages internally the optimal table - sizes as tables are modified.</p> - </dd> - <dt id="fileassoc_clear"><a class="permalink" href="#fileassoc_clear"><code class="Fn">fileassoc_clear</code></a>(<var class="Fa">vp</var>, - <var class="Fa">id</var>)</dt> - <dd>Clear the private data for <var class="Ar">vp</var>, for the fileassoc - specified by <var class="Ar">id</var>. - <p class="Pp">If specified, the fileassoc's “cleanup routine” - will be called with a pointer to the private data structure and - indication of <code class="Dv">FILEASSOC_CLEANUP_FILE</code>.</p> - </dd> -</dl> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">The following code examples should give you a clue on using - <code class="Nm">fileassoc</code> for your purposes.</p> -<p class="Pp">First, we'll begin with registering a new id. We need to do that - to save a slot for private data storage with each mount and/or file:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>fileassoc_t myhook_id; -int error; - -error = fileassoc_register("my_hook", myhook_cleanup, &myhook_id); -if (error != 0) - ...handle error...</pre> -</div> -<p class="Pp">In the above example we pass a - <code class="Fn">myhook_cleanup</code>() routine. It could look something - like this:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>void -myhook_cleanup(void *data) -{ - - printf("Myhook: Removing entry for file.\n"); - ...handle file entry removal... - free(data, M_TEMP); -}</pre> -</div> -<p class="Pp">Another useful thing would be to add our private data to a file. - For example, let's assume we keep a custom ACL with each file:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>int -myhook_acl_add(struct vnode *vp, struct myhook_acl *acl) -{ - int error; - - error = fileassoc_add(vp, myhook_id, acl); - if (error) { - printf("Myhook: Could not add ACL.\n"); - ...handle error... - } - - printf("Myhook: Added ACL.\n"); - - return (0); -}</pre> -</div> -<p class="Pp">Adding an entry will override any entry that previously - exists.</p> -<p class="Pp">Whatever your plug is, eventually you'll want to access the - private data you store with each file. To do that you can use the - following:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>int -myhook_acl_access(struct vnode *vp, int access_flags) -{ - struct myhook_acl *acl; - - acl = fileassoc_lookup(vp, myhook_id); - if (acl == NULL) - return (0); - - error = myhook_acl_eval(acl, access_flags); - if (error) { - printf("Myhook: Denying access based on ACL decision.\n"); - return (error); - } - - return (0); -}</pre> -</div> -<p class="Pp">And, in some cases, it may be desired to remove private data - associated with an file:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>int error; - -error = fileassoc_clear(vp, myhook_id); -if (error) { - printf("Myhook: Error occurred during fileassoc removal.\n"); - ...handle error... -}</pre> -</div> -<p class="Pp">As mentioned previously, the call to - <code class="Fn">fileassoc_clear</code>() will result in a call to the - “cleanup routine” specified in the initial call to - <code class="Fn">fileassoc_register</code>().</p> -<p class="Pp">The above should be enough to get you started.</p> -<p class="Pp">For example usage of <code class="Nm">fileassoc</code>, see the - Veriexec code.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE - REFERENCES</a></h1> -<p class="Pp">The <code class="Nm">fileassoc</code> is implemented within - <span class="Pa">src/sys/kern/kern_fileassoc.c</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">veriexec(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">fileassoc</code> KPI first appeared in - <span class="Ux">NetBSD 4.0</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp"><span class="An">Elad Efrat</span> - <<a class="Mt" href="mailto:elad@NetBSD.org">elad@NetBSD.org</a>> - <br/> - <span class="An">Brett Lymn</span> - <<a class="Mt" href="mailto:blymn@NetBSD.org">blymn@NetBSD.org</a>></p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">December 1, 2016</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |