lib/libc/gen/getvfsent.3

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