FILEASSOC(9)

NAME
fileassoc - in-kernel, file-system independent, file-meta data association

SYNOPSIS
#include <sys/fileassoc.h>

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

A system can have a maximum number of FILEASSOC_NHOOKS fileassocs associated with each file.

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.

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 fileassoc_register().

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-structures used by custom fileassocs) should be allocated and freed by the developer.

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.

fileassoc_t fileassoc_register(const char *name, fileassoc_cleanup_cb cleanup_cb)
    Registers a new fileassoc as name, and returns a fileassoc_t to be used as identifier in subsequent calls to the fileassoc subsystem, or -1 on failure.

    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 an int, 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 associated 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_tabledata_lookup(struct mount *mp, fileassoc_t id)
    Return table-wide private data in mp for id.

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_add(struct mount *mp, size_t size)
    Creates a new fileassoc table for mp with at least size slots.

int fileassoc_table_delete(struct mount *mp)
    Deletes a fileassoc table for mp.

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

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 and indication of either FILEASSOC_CLEANUP_FILE or FILEASSOC_CLEANUP_TABLE as appropriate.

int fileassoc_tabledata_add(struct mount *mp, fileassoc_t id, void *data)
    Add table-wide fileassoc-specific data in data to mp for id.

int fileassoc_tabledata_clear(struct mount *mp, fileassoc_t id)
    Clear table-wide fileassoc-specific data in mp for id.

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

    cb is a function returning void and receiving one void * parameter.

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

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

  Misc. Routines

void fileassoc_init(void)
    Initializes the fileassoc subsystem. fileassoc_init() is called once during system boot.

EXAMPLES
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;
    myhook_id = fileassoc_register("my_hook", myhook_cleanup);
    if (myhook_id == -1)
    	...handle error...

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

    void
    myhook_cleanup(void *data, int what)
    {
    	if (what == FILEASSOC_CLEANUP_FILE) {
    		printf("Myhook: Removing entry for file.);
    		...handle file entry removal...
    		free(data, M_TEMP);
    	} else if (what == FILEASSOC_CLEANUP_TABLE) {
    		printf("Myhook: Removing entry for mount.);
    		...handle mount 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:

    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.);
    		...handle error...
    	}
    	printf("Myhook: Added ACL.);
    	return (0);
    }

Adding an entry will override any entry that previously exists.

The above can fail, usually when there is no table for the mount. Creating a new table is simple:

    int error;
    error = fileassoc_table_add(vp-v_mount, nentries);
    if (error)
    	...handle error...

The second argument to fileassoc_table_add(), nentries, should be approximately the number of files it is predicted that will have entries in the table, although you can provide a pseudo-safe constant value (like 128, for example).

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:

    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.);
    		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 occured during fileassoc removal.);
    	...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 fileassoc_register().

The above should be enough to get you started.

For example usage of fileassoc, see the Veriexec code.

CODE REFERENCES
src/sys/kern/kern_verifiedexec.c

HISTORY
The fileassoc KPI first appeared in NetBSD 4.0.

AUTHORS
Elad Efrat <elad@NetBSD.org> Brett Lymn <blymn@NetBSD.org>