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

# NAME

`fileassoc` —
in-kernel, file system independent, file meta-data association

# SYNOPSIS

`#include <sys/fileassoc.h>`

int
`fileassoc_register`(const char *name, fileassoc_cleanup_cb_t cleanup_cb, fileassoc_t *result);

int
`fileassoc_deregister`(fileassoc_t id);

void *
`fileassoc_lookup`(struct vnode *vp, fileassoc_t id);

int
`fileassoc_table_delete`(struct mount *mp);

int
`fileassoc_table_clear`(struct mount *mp, fileassoc_t id);

int
`fileassoc_table_run`(struct mount *mp, fileassoc_t id, fileassoc_cb_t cb, void *cookie);

int
`fileassoc_file_delete`(struct vnode *vp);

int
`fileassoc_add`(struct vnode *vp, fileassoc_t id, void *data);

int
`fileassoc_clear`(struct vnode *vp, fileassoc_t id);

# DESCRIPTION

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

## REGISTRATION AND DEREGISTRATION ROUTINES

These routines allow a developer to allocate a `fileassoc` slot to be used for private data.

`fileassoc_register`(name, cleanup_cb, 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.

`fileassoc_deregister`(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.

`fileassoc_lookup`(vp, id)
  Returns the private data for the file/id combination or `NULL` if not found.

## MOUNT-WIDE ROUTINES

`fileassoc_table_delete`(mp)
  Deletes a fileassoc table for mp.
`fileassoc_table_clear`(mp, 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.

`fileassoc_table_run`(mp, id, cb, 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 two void * parameters.

## FILE-SPECIFIC ROUTINES

`fileassoc_file_delete`(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

`fileassoc_add`(vp, id, data)
  Add private data in data for vp, for the fileassoc specified by id.

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

`fileassoc_clear`(vp, 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`.

# 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;
    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:

    void
    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:

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

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:

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

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

The above should be enough to get you started.

For example usage of `fileassoc`, see the Veriexec code.

# CODE REFERENCES

The `fileassoc` is implemented within src/sys/kern/kern_fileassoc.c.

# SEE ALSO

veriexec(9)

# HISTORY

The `fileassoc` KPI first appeared in NetBSD 4.0.

# AUTHORS

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

December 1, 2016 | NetBSD 9.2