| FILEASSOC(9) | Kernel Developer's Manual | FILEASSOC(9) | 
fileassoc —
#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);
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.
fileassoc KPI
  usually accepts four different types of parameters to the most commonly used
  routines:
fileassoc_register().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
  slot to be used for private data.
fileassoc_register(name,
    cleanup_cb, result)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)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.
fileassoc mounts, files,
  and private data attached to them.
fileassoc_lookup(vp,
    id)NULL if not found.fileassoc_table_delete(mp)fileassoc_table_clear(mp,
    id)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)cb is a function returning void and receiving two void * parameters.
fileassoc_file_delete(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_add(vp,
    id, data)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)If specified, the fileassoc's “cleanup routine”
        will be called with a pointer to the private data structure and
        indication of FILEASSOC_CLEANUP_FILE.
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.
fileassoc is implemented within
  src/sys/kern/kern_fileassoc.c.
fileassoc KPI first appeared in
  NetBSD 4.0.
| December 1, 2016 | NetBSD 9.3 |