mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-17 10:26:15 +00:00
Document getvfsent() and kin.
This commit is contained in:
Garrett Wollman
parent
07ef895025
commit
d3ae7f1266
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=3062
@ -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
|
||||
|
||||
226
lib/libc/gen/getvfsent.3
Normal file
226
lib/libc/gen/getvfsent.3
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user