f153098d8f
in the main text of various man pages. Thanks to Warner Losh for adding an option to manck to allow it to scan the entire man page looking for bogus xrefs, instead of just checking the SEE ALSO section.
227 lines
5.2 KiB
Groff
227 lines
5.2 KiB
Groff
.\" $Id: getvfsent.3,v 1.1 1994/09/25 01:38:30 wollman Exp $
|
|
.\" 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 2 ,
|
|
.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.
|