GETVFSBYNAME(3)

NAME
getvfsbyname, getvfsbytype, getvfsent, setvfsent, endvfsent, vfsisloadable, vfsload - manage virtual filesystem modules

SYNOPSIS
#include <sys/mount.h>
struct vfsconf *
getvfsbyname(const char *name);
struct vfsconf *
getvfsbytype(int type);
struct vfsconf *
getvfsent(void);
void
setvfsent(int cachelist);
void
endvfsent(void);
int
vfsisloadable(const char *name);
int
vfsload(const char *name);

DESCRIPTION
The getvfsbyname(), getvfsbytype(), and getvfsent() functions provide convenient access to a list of installed virtual filesystem modules managed by the kernel. getvfsbyname() and getvfsbytype() provide direct access to a single filesystem's information; getvfsent() steps through the list of filesystems one at a time. All three functions return a null pointer when no data is available. The fields in a “struct vfsconf” are as follows:

vfc_name
    the name of the filesystem
vfc_index
    the filesystem type number assigned by the kernel and used in calls to mount(2)
vfc_refcount
    the number of references to this filesystem (usually the number of mounts, but one greater for filesystems which cannot be unloaded or which are statically linked into the kernel)
vfc_flags
    flag bits, of which none are currently defined

The setvfsent() and endvfsent() functions are used to control caching of the filesystem list, which is obtained in toto from the kernel via sysctl(3). If the cachelist parameter to setvfsent() is non-zero, the list will be retrieved only once, upon the first call to one of the retrieval functions, until endvfsent() is called to clear the cache. In general, setvfsent(1) should be called by programs using the getvfsent() function, and setvfsent(0) (which is also the default state) should be called by programs using the vfsload() function.

The vfsisloadable() function returns a non-zero value if a later call to vfsload(name) is likely to succeed. We say ``likely'' because the conditions checked by vfsisloadable() are only a small subset of the conditions necessary for vfsload() to succeed. In particular, vfsisloadable() checks that /dev/lkm is present and can be opened for writing, and that ~name_mod.o can be found in one of the directories designated for LKMs.

The vfsload() function attempts to load a kernel module implementing filesystem name. It returns zero if the filesystem module was successfully located and loaded, or non-zero otherwise. It should only be called in the following circumstances:

1.  getvfsbyname(name) has been called and returned a null pointer.

2.  vfsisloadable(name) has been called and returned a non-zero value.

3.  sufficient temporary file space is available and writable in one of ${TMPDIR}, /var/tmp, or /tmp.

Here is an example, taken from the source to mount_cd9660(8):

    struct vfsconf *vfc;
    /* setup code here */
    vfc = getvfsbyname("cd9660");
    if(!vfc && vfsisloadable("cd9660")) {
    	if(vfsload("cd9660"))
    		err(1, "vfsload(cd9660)");
    	endvfsent();	/* flush cache */
    	vfc = getvfsbyname("cd9660");
    }
    mount(vfc ? vfc->vfc_index : MOUNT_CD9660, /* more arguments */

The odd conditional in the call to mount(2) is present for compatibility with old, non-LKM cognizant kernels, and will be removed (along with all vestiges of MOUNT_*) in a future release.

RETURN VALUES
The getvfsbyname(), getvfsbytype(), and getvfsent() routines all return a pointer to the same static data structure when they succeed, and return a null pointer when they fail. On failure, errno may be set to one of the values documented for sysctl(3) or malloc(3), if a failure of that function was the cause; otherwise errno will be unmodified.

The vfsload() function returns a non-zero value on failure, or zero on success. If vfsload() fails, errno may be set to one of the values documented for fork(2), waitpid(2), chdir(2), or execlp(3), or the return status of the modload(8) program, which is not currently particularly useful but eventually will be. In addition, if modload(8) exits on a signal, vfsload() will fail and set errno to EINVAL.

ENVIRONMENT
TMPDIR
    location for temporary file created by modload(8) on behalf of vfsload().
LKMDIR
    alternate directory for vfsisloadable() and vfsload() to search for loadable modules.

SEE ALSO
modload(8), mount(2), mount(8)

BUGS
The return value of the modload(8) command isn't particularly useful when interpreted as an errno value (or anything else, for that matter).

AUTHOR
The loadable filesystem support was written by Garrett A. Wollman, based on generic loadable kernel module support by Terry Lambert.

HISTORY
The getvfsbyname() family of functions first appeared in FreeBSD 2.0.