Merge from vendor branch BZIP:
[dragonfly.git] / lib / libc / gen / getvfsent.3
CommitLineData
984263bc 1.\" $FreeBSD: src/lib/libc/gen/getvfsent.3,v 1.17.2.5 2001/12/14 18:33:51 ru Exp $
0b84df5c 2.\" $DragonFly: src/lib/libc/gen/getvfsent.3,v 1.3 2006/02/17 19:35:06 swildner Exp $
984263bc
MD
3.\" Written by Garrett A. Wollman, September 1994.
4.\" This manual page is in the public domain.
5.\"
6.Dd September 24, 1994
7.Dt GETVFSENT 3
8.Os
9.Sh NAME
10.Nm getvfsent ,
11.Nm setvfsent ,
12.Nm endvfsent ,
13.Nm vfsisloadable ,
14.Nm vfsload
15.Nd manage virtual filesystem modules
16.Sh LIBRARY
17.Lb libc
18.Sh SYNOPSIS
19.In sys/param.h
20.In sys/mount.h
21.Ft struct ovfsconf *
22.Fn getvfsent "void"
23.Ft void
24.Fn setvfsent "int cachelist"
25.Ft void
26.Fn endvfsent "void"
27.Ft int
28.Fn vfsisloadable "const char *name"
29.Ft int
30.Fn vfsload "const char *name"
31.Sh DESCRIPTION
32The
33.Fn getvfsent
34function provides convenient access to a list of installed virtual
35filesystem modules managed by the kernel. It steps through the
36list of filesystems one at a time. A null pointer is returned when
37no more data is available. The fields in a
38.Dq Li struct ovfsconf
39are as follows:
40.Pp
41.Bl -tag -compact -width vfc_refcount
42.It vfc_name
43the name of the filesystem
44.It vfc_index
45the filesystem type number assigned by the kernel and used in calls to
46.Xr mount 2
47.It vfc_refcount
48the number of references to this filesystem
49(usually the number of mounts, but one greater for filesystems which
50cannot be unloaded or which are statically linked into the kernel)
51.It vfc_flags
52flag bits
53.El
54.Pp
55The flags are defined as follows:
56.Pp
57.Bl -tag -width VFCF_SYNTHETIC -compact
58.It Dv VFCF_STATIC
59statically compiled into kernel
60.It Dv VFCF_NETWORK
61may get data over the network
62.It Dv VFCF_READONLY
63writes are not implemented
64.It Dv VFCF_SYNTHETIC
65data does not represent real files
66.It Dv VFCF_LOOPBACK
67aliases some other mounted FS
68.It Dv VFCF_UNICODE
69stores file names as Unicode
70.El
71.Pp
72The
73.Fn setvfsent
74and
75.Fn endvfsent
76functions are used to control caching of the filesystem list, which is
77obtained in toto from the kernel via
78.Xr sysctl 3 .
79If the
80.Fa cachelist
81parameter to
82.Fn setvfsent
83is non-zero, the list will be retrieved only once, upon the first call
84to one of the retrieval functions, until
85.Fn endvfsent
86is called to clear the cache. In general,
87.Fn setvfsent 1
88should be called by programs using the
89.Fn getvfsent
90function, and
91.Fn setvfsent 0
92(which is also the default state)
93should be called by programs using the
94.Fn vfsload
95function.
96.Pp
97The
98.Fn vfsisloadable
99function returns a non-zero value if a later call to
100.Fn vfsload name
101is likely to succeed. We say
102.Dq likely
103because
104.Fn vfsisloadable
105does not check any of the conditions necessary for
106.Fn vfsload
107to succeed.
108.Pp
109The
110.Fn vfsload
111function attempts to load a kernel module implementing filesystem
112.Fa name .
113It returns zero if the filesystem module was successfully located and
114loaded, or non-zero otherwise. It should only be called in the
115following circumstances:
116.Bl -enum
117.It
118.Fn getvfsbyname
119has been called and returned a non-zero value.
120.It
121.Fn vfsisloadable
122has been called and returned a non-zero value.
123.El
124.Pp
125Here is an example, taken from the source to
126.Xr mount_cd9660 8 :
127.Bd -literal -offset indent
128
129struct vfsconf *vfc;
130int error;
131
132/* setup code here */
133
134error = getvfsbyname("cd9660", &vfc);
135if (error && vfsisloadable("cd9660")) {
136 if (vfsload("cd9660"))
137 err(EX_OSERR, "vfsload(cd9660)");
138 endvfsent(); /* flush cache */
139 error = getvfsbyname("cd9660", &vfc);
140}
141if (error)
142 errx(1, "cd9660 filesystem is not available");
143
144if (mount(vfc.vfc_name, dir, mntflags, &args) < 0)
145 err(1, NULL);
146
147.Ed
148.Sh RETURN VALUES
149The
150.Fn getvfsent
151routine returns a pointer to a static data structure when
152it succeeds, and returns a null pointer when it fails. On failure,
153.Va errno
154may be set to one of the values documented for
155.Xr sysctl 3
156or
157.Xr malloc 3 ,
158if a failure of that function was the cause; otherwise
159.Va errno
160will be unmodified.
161.Pp
162The
163.Fn vfsload
164function returns a non-zero value on failure, or zero on success. If
165.Fn vfsload
166fails,
167.Va errno
168may be set to one of the values documented for
169.Xr kldload 2 .
170.Sh SEE ALSO
171.Xr kldload 2 ,
172.Xr mount 2 ,
173.Xr mount 8
0b84df5c
SW
174.Sh HISTORY
175The
176.Fn getvfsent
177family of functions first appeared in
178.Fx 2.0 .
984263bc
MD
179.Sh AUTHORS
180.An -nosplit
181The loadable filesystem support was written by
182.An Garrett A. Wollman ,
183based on generic loadable kernel module support by
184.An Terry Lambert .