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 FreeBSD system, there will be one geom
  47 of class MBR for each disk.
  48 The geom's name is not really important, it is only used in the XML
  49 dump and for debugging purposes.
  50 There can be many geoms with the same name.
  51 .Pp
  52 The
  53 .Fn g_new_geomf
  54 function creates a new geom, which will be an instance of the class
  55 .Fa mp .
  56 The geom's name is created in a printf-like way from the rest of the arguments.
  57 .Pp
  58 The
  59 .Fn g_destroy_geom
  60 function destroys the given geom immediately and cancels all related pending
  61 events.
  62 .Pp
  63 The
  64 .Vt g_geom
  65 structure
  66 contains fields that should be set by the caller after geom creation, but before
  67 creating any providers or consumers related to this geom (not all are required):
  68 .Bl -inset -offset indent
  69 .It Vt "g_start_t *" Va start
  70 Pointer to a function used for I/O processing.
  71 .It Vt "g_spoiled_t *" Va spoiled
  72 Pointer to a function used for consumers spoiling.
  73 .It Vt "g_dumpconf_t *" Va dumpconf
  74 Pointer to a function used for configuration in XML format dumping.
  75 .It Vt "g_access_t *" Va access
  76 Pointer to a function used for access control.
  77 .It Vt "g_orphan_t *" Va orphan
  78 Pointer to a function used to inform about orphaned consumer.
  79 .It Vt "g_ioctl_t *" Va ioctl
  80 Pointer to a function used for handling ioctl requests.
  81 .It Vt "void *" Va softc
  82 Field for private use.
  83 .El
  84 .Sh RESTRICTIONS/CONDITIONS
  85 If you intend to use providers in this geom you must set field
  86 .Va start
  87 of your geom.
  88 .Pp
  89 If you are planning to use consumers in your geom you must set fields
  90 .Va orphan
  91 and
  92 .Va access
  93 for it.
  94 .Pp
  95 .Fn g_new_geomf :
  96 .Bl -item -offset indent
  97 .It
  98 Class
  99 .Fa mp
 100 must be valid (registered in GEOM).
 101 .It
 102 The topology lock has to be held.
 103 .El
 104 .Pp
 105 .Fn g_destroy_geom :
 106 .Bl -item -offset indent
 107 .It
 108 The geom can not posses any providers.
 109 .It
 110 The geom can not posses any consumers.
 111 .It
 112 The topology lock has to be held.
 113 .El
 114 .Sh RETURN VALUES
 115 .Fn g_new_geomf
 116 returns a pointer to the newly created geom.
 117 .Sh EXAMPLES
 118 Create an example geom.
 119 .Bd -literal -offset indent
 120 static struct geom *
 121 g_example_start(struct bio *bp)
 122 {
 123
 124         [...]
 125 }
 126
 127 static void
 128 g_example_orphan(struct g_consumer *cp)
 129 {
 130
 131         g_topology_assert();
 132
 133         [...]
 134 }
 135
 136 static void
 137 g_example_spoiled(struct g_consumer *cp)
 138 {
 139
 140         g_topology_assert();
 141
 142         [...]
 143 }
 144
 145 static void
 146 g_example_access(struct g_provider *pp, int dr, int dw, int de)
 147 {
 148
 149         [...]
 150 }
 151
 152 static struct g_geom *
 153 create_example_geom(struct g_class *myclass)
 154 {
 155         struct g_geom *gp;
 156
 157         g_topology_lock();
 158         gp = g_new_geomf(myclass, "example_geom");
 159         g_topology_unlock();
 160         gp->start = g_example_start;
 161         gp->orphan = g_example_orphan;
 162         gp->spoiled = g_example_spoiled;
 163         gp->access = g_example_access;
 164         gp->softc = NULL;
 165
 166         return (gp);
 167 }
 168
 169 static int
 170 destroy_example_geom(struct g_geom *gp)
 171 {
 172
 173         g_topology_lock();
 174         if (!LIST_EMPTY(&gp->provider) ||
 175             !LIST_EMPTY(&gp->consumer)) {
 176                 g_topology_unlock();
 177                 return (EBUSY);
 178         }
 179         g_destroy_geom(gp);
 180         g_topology_unlock();
 181
 182         return (0);
 183 }
 184 .Ed
 185 .Sh SEE ALSO
 186 .Xr DECLARE_GEOM_CLASS 9 ,
 187 .Xr geom 4 ,
 188 .Xr g_access 9 ,
 189 .Xr g_attach 9 ,
 190 .Xr g_bio 9 ,
 191 .Xr g_consumer 9 ,
 192 .Xr g_data 9 ,
 193 .Xr g_event 9 ,
 194 .Xr g_provider 9 ,
 195 .Xr g_provider_by_name 9 ,
 196 .Xr g_wither_geom 9
 197 .Sh AUTHORS
 198 .An -nosplit
 199 This manual page was written by
 200 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .