Document getvfsent() and kin.

svn path=/head/; revision=3062

lib/libc/gen/Makefile.inc

@@ -1,5 +1,5 @@
 #	From: @(#)Makefile.inc	8.3 (Berkeley) 4/16/94
-#	$Id: Makefile.inc,v 1.10 1994/09/23 00:37:43 wollman Exp $
+#	$Id: Makefile.inc,v 1.11 1994/09/23 20:21:58 wollman Exp $
 
 # machine-independent gen sources
 .PATH: ${.CURDIR}/${MACHINE}/gen ${.CURDIR}/gen
@@ -42,7 +42,8 @@ MAN3+=	gen/alarm.3 gen/clock.3 gen/confstr.3 gen/crypt.3 gen/ctermid.3 \
 	gen/getcap.3 gen/getcwd.3 gen/getdiskbyname.3 gen/getfsent.3 \
 	gen/getgrent.3 gen/getgrouplist.3 gen/gethostname.3 gen/getloadavg.3 \
 	gen/getmntinfo.3 gen/getnetgrent.3 gen/getpagesize.3 gen/getpass.3 \
-	gen/getpwent.3 gen/getttyent.3 gen/getusershell.3 gen/glob.3 \
+	gen/getpwent.3 gen/getttyent.3 gen/getvfsent.3 gen/getusershell.3 \
+	gen/glob.3 \
 	gen/initgroups.3 gen/isinf.3 gen/ldexp.3 gen/modf.3 gen/nice.3 \
 	gen/nlist.3 gen/pause.3 gen/popen.3 gen/psignal.3 gen/pwcache.3 \
 	gen/raise.3 gen/rand48.3 gen/scandir.3 gen/setjmp.3 gen/setmode.3 \
@@ -76,6 +77,9 @@ MLINKS+=getnetgrent.3 endnetgrent.3 getnetgrent.3 setnetgrent.3 \
 MLINKS+=getpwent.3 endpwent.3 getpwent.3 setpassent.3 getpwent.3 getpwnam.3 \
 	getpwent.3 getpwuid.3 getpwent.3 setpwent.3 getpwent.3 setpwfile.3
 MLINKS+=getttyent.3 endttyent.3 getttyent.3 getttynam.3 getttyent.3 setttyent.3
+MLINKS+=getvfsent.3 getvfsbyname.3 getvfsent.3 getvfsbytype.3 \
+	getvfsent.3 setvfsent.3 getvfsent.3 endvfsent.3 \
+	getvfsent.3 vfsisloadable.3 getvfsent.3 vfsload.3
 MLINKS+=getusershell.3 endusershell.3 getusershell.3 setusershell.3
 MLINKS+=glob.3 globfree.3
 MLINKS+=popen.3 pclose.3

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.