diff options
author | wollman <wollman@FreeBSD.org> | 1994-09-25 01:38:30 +0000 |
---|---|---|
committer | wollman <wollman@FreeBSD.org> | 1994-09-25 01:38:30 +0000 |
commit | b0059b722709dfcef75ae3c33df7bf1f350ad220 (patch) | |
tree | ee6085548c60b134ca838f084e9579a77374c48c /lib/libc/gen/getvfsent.3 | |
parent | 81e5d29b29e56571d22821c3afae7000eadffd2f (diff) | |
download | FreeBSD-src-b0059b722709dfcef75ae3c33df7bf1f350ad220.zip FreeBSD-src-b0059b722709dfcef75ae3c33df7bf1f350ad220.tar.gz |
Document getvfsent() and kin.
Diffstat (limited to 'lib/libc/gen/getvfsent.3')
-rw-r--r-- | lib/libc/gen/getvfsent.3 | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/lib/libc/gen/getvfsent.3 b/lib/libc/gen/getvfsent.3 new file mode 100644 index 0000000..a8151b0 --- /dev/null +++ b/lib/libc/gen/getvfsent.3 @@ -0,0 +1,226 @@ +.\" $Id$ +.\" Written by Garrett A. Wollman, September 1994. +.\" This manual page is in the public domain. +.\" +.Dd September 24, 1994 +.Dt GETVFSBYNAME 3 +.Os +.Sh NAME +.Nm getvfsbyname , +.Nm getvfsbytype , +.Nm getvfsent , +.Nm setvfsent , +.Nm endvfsent , +.Nm vfsisloadable , +.Nm vfsload +.Nd manage virtual filesystem modules +.Sh SYNOPSIS +.Fd #include <sys/mount.h> +.Ft struct vfsconf * +.Fn getvfsbyname "const char *name" +.Ft struct vfsconf * +.Fn getvfsbytype "int type" +.Ft struct vfsconf * +.Fn getvfsent "void" +.Ft void +.Fn setvfsent "int cachelist" +.Ft void +.Fn endvfsent "void" +.Ft int +.Fn vfsisloadable "const char *name" +.Ft int +.Fn vfsload "const char *name" +.Sh DESCRIPTION +The +.Fn getvfsbyname , +.Fn getvfsbytype , +and +.Fn getvfsent +functions provide convenient access to a list of installed virtual +filesystem modules managed by the kernel. +.Fn getvfsbyname +and +.Fn getvfsbytype +provide direct access to a single filesystem's information; +.Fn 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 +.Dq Li struct vfsconf +are as follows: +.Pp +.Bl -tag -compact -width vfc_refcount +.It vfc_name +the name of the filesystem +.It vfc_index +the filesystem type number assigned by the kernel and used in calls to +.Xr mount 2 +.It 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) +.It vfc_flags +flag bits, of which none are currently defined +.El +.Pp +The +.Fn setvfsent +and +.Fn endvfsent +functions are used to control caching of the filesystem list, which is +obtained in toto from the kernel via +.Xr sysctl 3 . +If the +.Fa cachelist +parameter to +.Fn setvfsent +is non-zero, the list will be retrieved only once, upon the first call +to one of the retrieval functions, until +.Fn endvfsent +is called to clear the cache. In general, +.Fn setvfsent 1 +should be called by programs using the +.Fn getvfsent +function, and +.Fn setvfsent 0 +(which is also the default state) +should be called by programs using the +.Fn vfsload +function. +.Pp +The +.Fn vfsisloadable +function returns a non-zero value if a later call to +.Fn vfsload name +is likely to succeed. We say ``likely'' because the conditions +checked by +.Fn vfsisloadable +are only a small subset of the conditions necessary for +.Fn vfsload +to succeed. In particular, +.Fn vfsisloadable +checks that +.Pa /dev/lkm +is present and can be opened for writing, and that +.Pa Ns Fa name Ns _mod.o +can be found in one of the directories designated for LKMs. +.Pp +The +.Fn vfsload +function attempts to load a kernel module implementing filesystem +.Fa 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: +.Bl -enum +.It +.Fn getvfsbyname name +has been called and returned a null pointer. +.It +.Fn vfsisloadable name +has been called and returned a non-zero value. +.It +sufficient temporary file space is available +.Em and writable +in one of +.No Ns \&${ Ns Ev TMPDIR Ns \&} , +.Pa /var/tmp , +or +.Pa /tmp . +.El +.Pp +Here is an example, taken from the source to +.Xr mount_cd9660 8 : +.Bd -literal -offset indent + +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 */ + +.Ed +The odd conditional in the call to +.Xr mount 2 +is present for compatibility with old, non-LKM cognizant kernels, and +will be removed (along with all vestiges of +.Dv MOUNT_* ) +in a future release. +.Sh RETURN VALUES +The +.Fn getvfsbyname , +.Fn getvfsbytype , +and +.Fn 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, +.Va errno +may be set to one of the values documented for +.Xr sysctl 3 +or +.Xr malloc 3 , +if a failure of that function was the cause; otherwise +.Va errno +will be unmodified. +.Pp +The +.Fn vfsload +function returns a non-zero value on failure, or zero on success. If +.Fn vfsload +fails, +.Va errno +may be set to one of the values documented for +.Xr fork 2 , +.Xr waitpid 3 , +.Xr chdir 2 , +or +.Xr execlp 3 , +or the return status of the +.Xr modload 8 +program, which is not currently particularly useful but eventually +will be. In addition, if +.Xr modload 8 +exits on a signal, +.Fn vfsload +will fail and set +.Va errno +to +.Er EINVAL . +.Sh ENVIRONMENT +.Bl -tag -compact -width TMPDIRx +.It Ev TMPDIR +location for temporary file created by +.Xr modload 8 +on behalf of +.Fn vfsload . +.It Ev LKMDIR +alternate directory for +.Fn vfsisloadable +and +.Fn vfsload +to search for loadable modules. +.Sh SEE ALSO +.Xr modload 8 , +.Xr mount 2 , +.Xr mount 8 +.Sh BUGS +The return value of the +.Xr modload 8 +command isn't particularly useful when interpreted as an +.Va errno +value (or anything else, for that matter). +.Sh AUTHOR +The loadable filesystem support was written by Garrett A. Wollman, +based on generic loadable kernel module support by Terry Lambert. +.Sh HISTORY +The +.Fn getvfsbyname +family of functions first appeared in FreeBSD 2.0. |