1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
.\" $FreeBSD$
.\" 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/param.h>
.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
.Fx 2.0 .
|
