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