G_GEOM(9)

💅 G_GEOM(9) — geom management, but make it make sense

okay so bestie, you've stumbled into the Kernel Developer's Manual for G_GEOM(9) and honestly? iconic of you. this is the whole "how do i make and unmake a geom" situation, and i'm gonna hold your hand through it 🫶

---

✨ NAME ✨

g_new_geomf, g_destroy_geom — geom management, aka the birth and death of geoms 🎀

---

✨ SYNOPSIS ✨

first things first, you gotta invite the header:

#include <geom/geom.h>

then the two main characters:

struct g_geom *
g_new_geomf(struct g_class *mp, const char *fmt, ...);

void
g_destroy_geom(struct g_geom *gp);

---

✨ DESCRIPTION ✨

so. the geom — and do not confuse "geom" with "GEOM", they are literally not the same thing, i beg of you — is an instance of a GEOM class. 💫

for example: in a typical i386 FreeBSD system, there will be one geom of class MBR for each disk. like, one per disk, no cap.

and here's the thing — the geom's name is not really important. it's only used in the XML dump and for debugging purposes. that's it. you can have many geoms with the same name and nobody's gonna come for you. 🙈

the g_new_geomf() function creates a new geom, which will be an instance of the class mp. the geom's name is created in a printf(3)-like way from the rest of the arguments. fancy, right? slay.

the g_destroy_geom() function destroys the given geom immediately and cancels all related pending events. like, gone. no farewell tour. 💀

---

🌸 the g_geom struct fields you gotta set

the g_geom structure contains fields that should be set by the caller after geom creation, but before creating any providers or consumers related to this geom 💖 (not all are required, so breathe):

• g_start_t * start — pointer to a function used for I/O processing.
• g_spoiled_t * spoiled — pointer to a function used for consumers spoiling.
• g_dumpconf_t * dumpconf — pointer to a function used for configuration in XML format dumping.
• g_access_t * access — pointer to a function used for access control.
• g_orphan_t * orphan — pointer to a function used to inform about orphaned consumer.
• g_ioctl_t * ioctl — pointer to a function used for handling ioctl requests.
• void * softc — field for private use. yours. do what you want. 👑

---

✨ RESTRICTIONS/CONDITIONS ✨

okay this is the rules section, and the rules are rules — lowkey important, highkey mandatory:

if you intend to use providers in this geom you must set field start of your geom. periodt.

if you are planning to use consumers in your geom you must set fields orphan and access for it.

now for g_new_geomf():

• Class mp must be valid (registered in GEOM).
• The topology lock has to be held.

and for g_destroy_geom():

• The geom cannot possess any providers.
• The geom cannot possess any consumers.
• The topology lock has to be held.

literally do not forget the topology lock. i'm not gonna say it again (i will say it again).

---

✨ RETURN VALUES ✨

the g_new_geomf() function returns a pointer to the newly created geom. that's the whole vibe check. 🦋

---

✨ EXAMPLES ✨

bestie, we're creating an example geom. watch and learn 🌈

static void
g_example_start(struct bio *bp)
{

    [...]
}

static void
g_example_orphan(struct g_consumer *cp)
{

    g_topology_assert();

    [...]
}

static void
g_example_spoiled(struct g_consumer *cp)
{

    g_topology_assert();

    [...]
}

static int
g_example_access(struct g_provider *pp, int dr, int dw, int de)
{

    [...]
}

static struct g_geom *
create_example_geom(struct g_class *myclass)
{
    struct g_geom *gp;

    g_topology_lock();
    gp = g_new_geomf(myclass, "example_geom");
    g_topology_unlock();
    gp->start = g_example_start;
    gp->orphan = g_example_orphan;
    gp->spoiled = g_example_spoiled;
    gp->access = g_example_access;
    gp->softc = NULL;

    return (gp);
}

static int
destroy_example_geom(struct g_geom *gp)
{

    g_topology_lock();
    if (!LIST_EMPTY(&gp->provider) ||
        !LIST_EMPTY(&gp->consumer)) {
        g_topology_unlock();
        return (EBUSY);
    }
    g_destroy_geom(gp);
    g_topology_unlock();

    return (0);
}

see how create_example_geom locks the topology, makes the geom, unlocks, and then assigns all the function pointers? that's the whole flow, and it ate. 🔥 and destroy_example_geom checks both lists are empty first before calling g_destroy_geom — otherwise it bails with EBUSY. no cap.

---

✨ SEE ALSO ✨

go read these next, i'm obsessed with your curiosity 💜

geom(4), DECLARE_GEOM_CLASS(9), g_access(9), g_attach(9), g_bio(9), g_consumer(9), g_data(9), g_event(9), g_provider(9), g_provider_by_name(9), g_wither_geom(9)

---

✨ AUTHORS ✨

This manual page was written by Pawel Jakub Dawidek <pjd@FreeBSD.org>. ty king 👑

---

and that's the page, bestie — this Debian-flavoured G_GEOM(9) dropped April 24, 2016, and you just read the whole thing. go forth and manage your geoms responsibly 💖✨🎀