Unix/Linux Go Back    


NetBSD 6.1.5 - man page for fileassoc (netbsd section 9)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


FILEASSOC(9)			  BSD 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 sup-
     port 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 one void * parameter.

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

HISTORY
     The fileassoc KPI first appeared in NetBSD 4.0.

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

BSD					 January 26, 2010				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:59 PM.