share/man/man9/kernel_mount.9

   1 .\"
   2 .\" Copyright (c) 2004 Tom Rhodes
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd December 13, 2004
  29 .Dt KERNEL_MOUNT 9
  30 .Os
  31 .Sh NAME
  32 .Nm free_mntarg ,
  33 .Nm kernel_mount ,
  34 .Nm kernel_vmount ,
  35 .Nm mount_arg ,
  36 .Nm mount_argb ,
  37 .Nm mount_argf ,
  38 .Nm mount_argsu
  39 .Nd "functions provided as part of the kernel mount interface"
  40 .Sh SYNOPSIS
  41 .Ft void
  42 .Fn free_mntarg "struct mntarg *ma"
  43 .Ft int
  44 .Fn kernel_mount "struct mntarg *ma" "int flags"
  45 .Ft int
  46 .Fn kernel_vmount "int flags" ...
  47 .Ft "struct mntarg *"
  48 .Fo mount_arg
  49 .Fa "struct mntarg *ma" "const char *name" "const void *val" "int len"
  50 .Fc
  51 .Ft "struct mntarg *"
  52 .Fn mount_argb "struct mntarg *ma" "int flag" "const char *name"
  53 .Ft "struct mntarg *"
  54 .Fn mount_argf "struct mntarg *ma" "const char *name" "const char *fmt" ...
  55 .Ft "struct mntarg *"
  56 .Fo mount_argsu
  57 .Fa "struct mntarg *ma" "const char *name" "const void *val" "int len"
  58 .Fc
  59 .Sh DESCRIPTION
  60 The
  61 .Fn kernel_mount
  62 family of functions are provided as an API for building a list
  63 of mount arguments which will be used to mount file systems
  64 from inside the kernel.
  65 By accumulating a list of arguments, the API takes shape and
  66 provides the information necessary for the kernel to control
  67 the
  68 .Xr mount 8
  69 utility.
  70 When an error occurs, the process will stop.
  71 This will not cause a
  72 .Xr panic 9 .
  73 .Pp
  74 The header of the structure is stored in
  75 .Pa src/sys/kern/vfs_mount.c
  76 which permits automatic structure creation to
  77 ease the mount process.
  78 Memory allocation must always be freed when the entire
  79 process is complete, it is an error otherwise.
  80 .Pp
  81 The
  82 .Fn free_mntarg
  83 function is used to free or clear the
  84 .Vt mntarg
  85 structure.
  86 .Pp
  87 The
  88 .Fn kernel_mount
  89 function pulls information from the structure to perform
  90 the mount request on a given file system.
  91 Additionally, the
  92 .Fn kernel_mount
  93 function always calls the
  94 .Fn free_mntarg
  95 function.
  96 If
  97 .Fa ma
  98 contains any error code generated during the construction,
  99 that code will be called and the file system mount will
 100 not be attempted.
 101 .Pp
 102 The
 103 .Fn kernel_vmount
 104 is a function similar to
 105 .Xr printf 9
 106 which is used to mount a file system.
 107 .Pp
 108 The
 109 .Fn mount_arg
 110 function takes a plain argument and crafts parts of
 111 the structure with regards to various mount options.
 112 If the length is a value less than 0,
 113 .Xr strlen 3
 114 is used.
 115 This argument will be referenced until either
 116 .Fn free_mntarg
 117 or
 118 .Fn kernel_mount
 119 is called.
 120 .Pp
 121 The
 122 .Fn mount_argb
 123 function is used to add boolean arguments to
 124 the structure.
 125 The
 126 .Fa flag
 127 is the boolean value and
 128 .Fa name
 129 must start with
 130 .Qq Li no ,
 131 otherwise a panic will occur.
 132 .Pp
 133 The
 134 .Fn mount_argf
 135 function adds
 136 .Xr printf 9
 137 style arguments to the current structure.
 138 .Pp
 139 The
 140 .Fn mount_argsu
 141 function will add arguments to the structure from a
 142 userland string.
 143 .Sh EXAMPLES
 144 An example of the
 145 .Fn *_cmount
 146 function:
 147 .Bd -literal
 148 static int
 149 msdosfs_cmount(struct mntarg *ma, void *data, int flags, struct thread *td)
 150 {
 151         struct msdosfs_args args;
 152         int error;
 153
 154         if (data == NULL)
 155                 return (EINVAL);
 156         error = copyin(data, &args, sizeof args);
 157         if (error)
 158                 return (error);
 159
 160         ma = mount_argsu(ma, "from", args.fspec, MAXPATHLEN);
 161         ma = mount_arg(ma, "export", &args.export, sizeof args.export);
 162         ma = mount_argf(ma, "uid", "%d", args.uid);
 163         ma = mount_argf(ma, "gid", "%d", args.gid);
 164         ma = mount_argf(ma, "mask", "%d", args.mask);
 165         ma = mount_argf(ma, "dirmask", "%d", args.dirmask);
 166
 167         ma = mount_argb(ma, args.flags & MSDOSFSMNT_SHORTNAME, "noshortname");
 168         ma = mount_argb(ma, args.flags & MSDOSFSMNT_LONGNAME, "nolongname");
 169         ma = mount_argb(ma, !(args.flags & MSDOSFSMNT_NOWIN95), "nowin95");
 170         ma = mount_argb(ma, args.flags & MSDOSFSMNT_KICONV, "nokiconv");
 171
 172         ma = mount_argsu(ma, "cs_win", args.cs_win, MAXCSLEN);
 173         ma = mount_argsu(ma, "cs_dos", args.cs_dos, MAXCSLEN);
 174         ma = mount_argsu(ma, "cs_local", args.cs_local, MAXCSLEN);
 175
 176         error = kernel_mount(ma, flags);
 177
 178         return (error);
 179 }
 180 .Ed
 181 .Pp
 182 When working with
 183 .Fn kernel_vmount ,
 184 .Fa varargs
 185 must come in pairs, e.g.,
 186 .Brq Va name , value .
 187 .Bd -literal
 188         error = kernel_vmount(
 189             MNT_RDONLY,
 190             "fstype", vfsname,
 191             "fspath", "/",
 192             "from", path,
 193             NULL);
 194 .Ed
 195 .Sh SEE ALSO
 196 .Xr VFS 9 ,
 197 .Xr VFS_MOUNT 9 ,
 198 .Xr vfs_mount 9
 199 .Sh HISTORY
 200 The
 201 .Fn kernel_mount
 202 family of functions and this manual page first
 203 appeared in
 204 .Fx 6.0 .
 205 .Sh AUTHORS
 206 .An -nosplit
 207 The
 208 .Fn kernel_mount
 209 family of functions and API was developed by
 210 .An Poul-Henning Kamp Aq phk@FreeBSD.org .
 211 This manual page was written by
 212 .An Tom Rhodes Aq trhodes@FreeBSD.org .