G_GEOM(9)

💅 G_GEOM(9) — the kernel dev manual, but make it make sense 💅

okay so bestie, welcome to the g_geom page from the Kernel Developer's Manual. yes it's section 9. yes that's the big-kid section. we're doing geom management today and honestly? it's giving main character energy. 🎀

---

✨ NAME ✨

g_new_geomf, g_destroy_geom — geom management

like. that's the whole vibe. making geoms, unmaking geoms. 💖

---

🦋 SYNOPSIS 🦋

#include <geom/geom.h>

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

void
g_destroy_geom(struct g_geom *gp);

---

🌸 DESCRIPTION 🌸

So. A geom (and pls do not confuse “geom” with “GEOM”, they are not the same thing, iykyk) is an instance of a GEOM class. Example time: in a typical i386 FreeBSD system, there's gonna be one geom of class MBR for every single disk. one per disk. that's the whole thing.

And here's the tea — the geom's name is not really important. it's only used in the XML dump and for debugging purposes. There can be many geoms with the same name. no cap. duplicate names everywhere and nobody's mad about it. 🫶

The g_new_geomf() function creates a new geom, which will be an instance of the class mp. The geom's name gets created in a printf(3)-like way from the rest of the arguments. so it's format-string girlie behaviour. ✨

The g_destroy_geom() function destroys the given geom immediately and cancels all related pending events. instant. no waiting around. 💀

---

🎀 the g_geom structure fields 🎀

okay so the g_geom structure has fields that should be set by the caller after geom creation, but before creating any providers or consumers related to this geom. and ngl, not all of them are required — but here's the full list:

• 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.

set them early, bestie. don't be the girl who sets start after making providers. 🙈

---

🔥 RESTRICTIONS/CONDITIONS 🔥

okay this is the rules section and we respect the rules. 🫡

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. both of them. not one. both. 💅

---

⭐ g_new_geomf(): ⭐

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

---

⭐ g_destroy_geom(): ⭐

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

🚨 bestie listen — if you're still holding providers or consumers when you call destroy, that's not a vibe check you're gonna pass. clean up first.

---

💖 RETURN VALUES 💖

The g_new_geomf() function returns a pointer to the newly created geom. that's it, that's the return. iconic behaviour honestly, no weird error codes to memorise. ✨

---

🧚 EXAMPLES 🧚

okay so let's create an example geom. watch and learn, babe. 👑

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 we lock, create, unlock, then set the function pointers? that's the order. do not freestyle it. 💅 and in the destroy path we check LIST_EMPTY(&gp->provider) and LIST_EMPTY(&gp->consumer) first and bail with EBUSY if either one's got stuff in it. queen behaviour. 👑

---

🌈 SEE ALSO 🌈

• 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)

go read them. all of them. that's your homework bestie. 🍓

---

💜 AUTHORS 💜

This manual page was written by Pawel Jakub Dawidek <pjd@FreeBSD.org>. king behaviour, we love him for it. 🫶

---

and that's the whole page, babe!! 🌸 this one's from the Debian crew, dated April 24, 2016, and it lives in section G_GEOM(9) of the Kernel Developer's Manual. go forth and manage your geoms responsibly. mwah. 💋