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