1.\" $FreeBSD: src/lib/libc/gen/getvfsent.3,v 1.17.2.5 2001/12/14 18:33:51 ru Exp $ 2.\" $DragonFly: src/lib/libc/gen/getvfsent.3,v 1.3 2006/02/17 19:35:06 swildner Exp $ 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 174.Sh HISTORY 175The 176.Fn getvfsent 177family of functions first appeared in 178.Fx 2.0 . 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 . 185