summaryrefslogtreecommitdiffstats
path: root/lib/libc/gen/getvfsent.3
blob: 7c4a9340a8bc2330505db79060fd41b61f029754 (plain)
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
.\" $FreeBSD$
.\"	Written by Garrett A. Wollman, September 1994.
.\"	This manual page is in the public domain.
.\"
.Dd September 24, 1994
.Dt GETVFSENT 3
.Os
.Sh NAME
.Nm getvfsent ,
.Nm setvfsent ,
.Nm endvfsent ,
.Nm vfsisloadable ,
.Nm vfsload
.Nd manage virtual file system modules
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/param.h
.In sys/mount.h
.Ft struct ovfsconf *
.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 getvfsent
function provides convenient access to a list of installed virtual
file system modules managed by the kernel.  It steps through the
list of file systems one at a time.  A null pointer is returned when
no more data is available.  The fields in a
.Dq Li struct ovfsconf
are as follows:
.Pp
.Bl -tag -compact -width vfc_refcount
.It vfc_name
the name of the file system
.It vfc_index
the file system type number assigned by the kernel and used in calls to
.Xr mount 2
.It vfc_refcount
the number of references to this file system
(usually the number of mounts, but one greater for file systems which
cannot be unloaded or which are statically linked into the kernel)
.It vfc_flags
flag bits
.El
.Pp
The flags are defined as follows:
.Pp
.Bl -tag -width VFCF_SYNTHETIC -compact
.It Dv VFCF_STATIC
statically compiled into kernel
.It Dv VFCF_NETWORK
may get data over the network
.It Dv VFCF_READONLY
writes are not implemented
.It Dv VFCF_SYNTHETIC
data does not represent real files
.It Dv VFCF_LOOPBACK
aliases some other mounted FS
.It Dv VFCF_UNICODE
stores file names as Unicode
.El
.Pp
The
.Fn setvfsent
and
.Fn endvfsent
functions are used to control caching of the file system list, which is
obtained in toto from the kernel via
.Xr sysctl 3 .
If the
.Fa cachelist
argument 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
.Dq likely
because
.Fn vfsisloadable
does not check any of the conditions necessary for
.Fn vfsload
to succeed.
.Pp
The
.Fn vfsload
function attempts to load a kernel module implementing file system
.Fa name .
It returns zero if the file system module was successfully located and
loaded, or non-zero otherwise.  It should only be called in the
following circumstances:
.Bl -enum
.It
The
.Fn getvfsbyname
function
has been called and returned a non-zero value.
.It
The
.Fn vfsisloadable
function
has been called and returned a non-zero value.
.El
.Pp
Here is an example, taken from the source to
.Xr mount_cd9660 8 :
.Bd -literal -offset indent

struct vfsconf *vfc;
int error;

/* setup code here */

error = getvfsbyname("cd9660", &vfc);
if (error && vfsisloadable("cd9660")) {
	if (vfsload("cd9660"))
		err(EX_OSERR, "vfsload(cd9660)");
	endvfsent();	/* flush cache */
	error = getvfsbyname("cd9660", &vfc);
}
if (error)
	errx(1, "cd9660 filesystem is not available");

if (mount(vfc.vfc_name, dir, mntflags, &args) < 0)
	err(1, NULL);

.Ed
.Sh RETURN VALUES
The
.Fn getvfsent
routine returns a pointer to a static data structure when
it succeeds, and returns a null pointer when it fails.  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 kldload 2 .
.Sh SEE ALSO
.Xr kldload 2 ,
.Xr mount 2 ,
.Xr mount 8
.Sh AUTHORS
.An -nosplit
The loadable file system support was written by
.An Garrett A. Wollman ,
based on generic loadable kernel module support by
.An Terry Lambert .
.Sh HISTORY
The
.Fn getvfsent
family of functions first appeared in
.Fx 2.0 .
OpenPOWER on IntegriCloud