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