FILEASSOC(9)           NetBSD Kernel Developer's Manual           FILEASSOC(9)

     fileassoc -- in-kernel, file-system independent, file-meta data associa-

     #include <sys/fileassoc.h>

     The fileassoc KPI allows association of meta-data with files independent
     of file-system support for such elaborate meta-data.

     When plugging a new fileassoc to the system, a developer can specify pri-
     vate data to be associated with every file, as well as (potentially dif-
     ferent) private data to be associated with every file-system mount.

     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.

   Kernel Programming Interface
     Designed with simplicity in mind, the fileassoc KPI usually accepts four
     different types of parameters to the most commonly used routines:

     struct mount * mp
             Describing a mount on which to take action.

     struct vnode * vp
             Describing a file on which to take action.

     fileassoc_t id
             Describing an id, as returned from a successful call to

     void * data
             Describing a custom private data block, attached to either a file
             or a mount.

     Before using the fileassoc KPI it is important to keep in mind that the
     interface provides memory management only for fileassoc internal memory.
     Any additional memory stored in the tables (such as private data-struc-
     tures used by custom fileassocs) should be allocated and freed by the

     fileassoc provides the ability to specify a ``cleanup'' routine to
     fileassoc_register() (see below) to be called whenever an entry for a
     file or a mount is deleted.

   Fileassoc Registration and Deregistration Routines
     These routines allow a developer to allocate a fileassoc slot to be used
     for private data.

     int fileassoc_register(const char *name, fileassoc_cleanup_cb_t
             cleanup_cb, fileassoc_t *result)
             Registers a new fileassoc as name, and returns a fileassoc_t via
             result to be used as identifier in subsequent calls to the
             fileassoc subsystem.

             fileassoc_register() returns zero on success.  Otherwise, an
             error number will be returned.

             If cleanup_cb is not NULL, it will be called during delete/clear
             operations (see routines below) with indication whether the
             passed data is file- or mount-specific.

             cleanup_cb should be a function receiving a void * and returning
             void.  See the EXAMPLES section for illustration.

     int fileassoc_deregister(fileassoc_t id)
             Deregisters a fileassoc whose id is id.

             Note that calling fileassoc_deregister() only frees the associ-
             ated slot in the fileassoc subsystem.  It is up to the developer
             to take care of garbage collection.

   Lookup Routines
     These routines allow lookup of fileassoc mounts, files, and private data
     attached to them.

     void * fileassoc_lookup(struct vnode *vp, fileassoc_t id)
             Returns the private data for the file/id combination or NULL if
             not found.

   Mount-wide Routines
     int fileassoc_table_delete(struct mount *mp)
             Deletes a fileassoc table for mp.

     int fileassoc_table_clear(struct mount *mp, fileassoc_t id)
             Clear all table entries for fileassoc from mp.

             If specified, the fileassoc's ``cleanup routine'' will be called
             with a pointer to the private data-structure.

     int fileassoc_table_run(struct mount *mp, fileassoc_t id, fileassoc_cb_t
             cb, void *cookie)
             For each entry for id, call cb with the entry being the first
             argument, and cookie being the second argument.

             cb is a function returning void and receiving one void * parame-

   File-specific Routines
     int fileassoc_file_delete(struct vnode *vp)
             Delete the fileassoc entries for vp.

             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 FILEASSOC_CLEANUP_FILE.

   Fileassoc-specific Routines
     int fileassoc_add(struct vnode *vp, fileassoc_t id, void *data)
             Add private data in data for vp, for the fileassoc specified by

             If a table for the mount-point vp is on doesn't exist, one will
             be created automatically.  fileassoc manages internally the opti-
             mal table sizes as tables are modified.

     int fileassoc_clear(struct vnode *vp, fileassoc_t id)
             Clear the private data for vp, for the fileassoc specified by id.

             If specified, the fileassoc's ``cleanup routine'' will be called
             with a pointer to the private data-structure and indication of

     The following code examples should give you a clue on using fileassoc for
     your purposes.

     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:

           fileassoc_t myhook_id;
           int error;

           error = fileassoc_register("my_hook", myhook_cleanup, &myhook_id);
           if (error != 0)
                   ...handle error...

     In the above example we pass a myhook_cleanup() routine.  It could look
     something like this:

           myhook_cleanup(void *data)

                   printf("Myhook: Removing entry for file.\n");
                   ...handle file entry removal...
                   free(data, M_TEMP);

     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:

           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);

     Adding an entry will override any entry that previously exists.

     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:

           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);

     And, in some cases, it may be desired to remove private data associated
     with an file:

           int error;

           error = fileassoc_clear(vp, myhook_id);
           if (error) {
                   printf("Myhook: Error occurred during fileassoc removal.\n");
                   ...handle error...

     As mentioned previously, the call to fileassoc_clear() will result in a
     call to the ``cleanup routine'' specified in the initial call to

     The above should be enough to get you started.

     For example usage of fileassoc, see the Veriexec code.


     The fileassoc KPI first appeared in NetBSD 4.0.

     Elad Efrat <>
     Brett Lymn <>

NetBSD 5.1                       May 15, 2007                       NetBSD 5.1

You can also request any man page by name and (optionally) by section:


Use the DEFAULT collection to view manual pages for third-party software.

©1994 Man-cgi 1.15, Panagiotis Christias
©1996-2018 Modified for NetBSD by Kimmo Suominen