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>