share/man/man9/g_geom.9

   1 .\"
   2 .\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org>
   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 DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd January 16, 2004
  28 .Dt G_GEOM 9
  29 .Os
  30 .Sh NAME
  31 .Nm g_new_geomf ,
  32 .Nm g_destroy_geom
  33 .Nd "geom management"
  34 .Sh SYNOPSIS
  35 .In geom/geom.h
  36 .Ft "struct g_geom *"
  37 .Fn g_new_geomf "struct g_class *mp" "const char *fmt" ...
  38 .Ft void
  39 .Fn g_destroy_geom "struct g_geom *gp"
  40 .Sh DESCRIPTION
  41 The geom (do not confuse
  42 .Dq geom
  43 with
  44 .Dq GEOM )
  45 is an instance of a GEOM class.
  46 For example: in a typical i386
  47 .Fx
  48 system, there will be one geom
  49 of class MBR for each disk.
  50 The geom's name is not really important, it is only used in the XML
  51 dump and for debugging purposes.
  52 There can be many geoms with the same name.
  53 .Pp
  54 The
  55 .Fn g_new_geomf
  56 function creates a new geom, which will be an instance of the class
  57 .Fa mp .
  58 The geom's name is created in a
  59 .Xr printf 3 Ns
  60 -like way from the rest of the arguments.
  61 .Pp
  62 The
  63 .Fn g_destroy_geom
  64 function destroys the given geom immediately and cancels all related pending
  65 events.
  66 .Pp
  67 The
  68 .Vt g_geom
  69 structure
  70 contains fields that should be set by the caller after geom creation, but before
  71 creating any providers or consumers related to this geom (not all are required):
  72 .Bl -tag -offset indent -width indent
  73 .It Vt "g_start_t *" Va start
  74 Pointer to a function used for I/O processing.
  75 .It Vt "g_spoiled_t *" Va spoiled
  76 Pointer to a function used for consumers spoiling.
  77 .It Vt "g_dumpconf_t *" Va dumpconf
  78 Pointer to a function used for configuration in XML format dumping.
  79 .It Vt "g_access_t *" Va access
  80 Pointer to a function used for access control.
  81 .It Vt "g_orphan_t *" Va orphan
  82 Pointer to a function used to inform about orphaned consumer.
  83 .It Vt "g_ioctl_t *" Va ioctl
  84 Pointer to a function used for handling ioctl requests.
  85 .It Vt "void *" Va softc
  86 Field for private use.
  87 .El
  88 .Sh RESTRICTIONS/CONDITIONS
  89 If you intend to use providers in this geom you must set field
  90 .Va start
  91 of your geom.
  92 .Pp
  93 If you are planning to use consumers in your geom you must set fields
  94 .Va orphan
  95 and
  96 .Va access
  97 for it.
  98 .Pp
  99 .Fn g_new_geomf :
 100 .Bl -item -offset indent
 101 .It
 102 Class
 103 .Fa mp
 104 must be valid (registered in GEOM).
 105 .It
 106 The topology lock has to be held.
 107 .El
 108 .Pp
 109 .Fn g_destroy_geom :
 110 .Bl -item -offset indent
 111 .It
 112 The geom cannot possess any providers.
 113 .It
 114 The geom cannot possess any consumers.
 115 .It
 116 The topology lock has to be held.
 117 .El
 118 .Sh RETURN VALUES
 119 The
 120 .Fn g_new_geomf
 121 function
 122 returns a pointer to the newly created geom.
 123 .Sh EXAMPLES
 124 Create an example geom.
 125 .Bd -literal -offset indent
 126 static struct geom *
 127 g_example_start(struct bio *bp)
 128 {
 129
 130         [...]
 131 }
 132
 133 static void
 134 g_example_orphan(struct g_consumer *cp)
 135 {
 136
 137         g_topology_assert();
 138
 139         [...]
 140 }
 141
 142 static void
 143 g_example_spoiled(struct g_consumer *cp)
 144 {
 145
 146         g_topology_assert();
 147
 148         [...]
 149 }
 150
 151 static void
 152 g_example_access(struct g_provider *pp, int dr, int dw, int de)
 153 {
 154
 155         [...]
 156 }
 157
 158 static struct g_geom *
 159 create_example_geom(struct g_class *myclass)
 160 {
 161         struct g_geom *gp;
 162
 163         g_topology_lock();
 164         gp = g_new_geomf(myclass, "example_geom");
 165         g_topology_unlock();
 166         gp->start = g_example_start;
 167         gp->orphan = g_example_orphan;
 168         gp->spoiled = g_example_spoiled;
 169         gp->access = g_example_access;
 170         gp->softc = NULL;
 171
 172         return (gp);
 173 }
 174
 175 static int
 176 destroy_example_geom(struct g_geom *gp)
 177 {
 178
 179         g_topology_lock();
 180         if (!LIST_EMPTY(&gp->provider) ||
 181             !LIST_EMPTY(&gp->consumer)) {
 182                 g_topology_unlock();
 183                 return (EBUSY);
 184         }
 185         g_destroy_geom(gp);
 186         g_topology_unlock();
 187
 188         return (0);
 189 }
 190 .Ed
 191 .Sh SEE ALSO
 192 .Xr geom 4 ,
 193 .Xr DECLARE_GEOM_CLASS 9 ,
 194 .Xr g_access 9 ,
 195 .Xr g_attach 9 ,
 196 .Xr g_bio 9 ,
 197 .Xr g_consumer 9 ,
 198 .Xr g_data 9 ,
 199 .Xr g_event 9 ,
 200 .Xr g_provider 9 ,
 201 .Xr g_provider_by_name 9 ,
 202 .Xr g_wither_geom 9
 203 .Sh AUTHORS
 204 .An -nosplit
 205 This manual page was written by
 206 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .