G_ATTACH(9)

💖 G_ATTACH — bestie's guide to gluing GEOM consumers to providers 💖

okay so this is the G_ATTACH(9) page from the Kernel Developer's Manual, and honestly? it's a whole vibe. it's about g_attach and g_detach, aka the two functions that decide whether a GEOM consumer and a GEOM provider are talking or not talking. situationship management, basically. 💅

---

✨ NAME ✨

g_attach, g_detach — attach/detach GEOM consumers to/from providers

---

🌸 SYNOPSIS 🌸

#include <geom/geom.h>

int
g_attach(struct g_consumer *cp, struct g_provider *pp);

void
g_detach(struct g_consumer *cp);

---

💖 DESCRIPTION 💖

so the g_attach() function takes the consumer you hand it, cp, and attaches it to the provider you hand it, pp. that's it, that's the matchmaking. and what it does is establish a communication channel between the consumer and the provider — a little private line between them 🫶 — which is what lets you change access counts and do I/O operations. no channel, no I/O, simple as.

then g_detach() is the breakup arc 😭. it detaches the given consumer cp from whatever provider it's currently corresponding with, and it tears down that communication channel between them. gone. done. no more talking.

---

🎀 RESTRICTIONS/CONDITIONS 🎀

bestie these are not suggestions, these are the rules, and the kernel will be mad at you if you break them. ✋

for g_attach():

• the consumer must not already be attached to a provider (no double-dipping, that's not the vibe)
• the operation must not create a topology loop (do NOT make the geometry eat itself 🌀💀)
• the topology lock has to be held

for g_detach():

• the consumer has to be attached (you can't detach from nothing, bestie)
• the access count has to be 0
• there must be no active requests
• the topology lock has to be held

---

⭐ RETURN VALUES ⭐

g_attach() is a queen that reports back: it returns 0 when it's successful. otherwise? it hands you an error code instead. so like, always check it. always. 👑

---

🌈 EXAMPLES 🌈

here's the whole glow-up routine: create a consumer, attach it to a given provider, gain read access, and then clean up after yourself like a responsible icon. 🧹✨

void
some_function(struct g_geom *mygeom, struct g_provider *pp)
{
    struct g_consumer *cp;

    g_topology_assert();

    /* Create new consumer on 'mygeom' geom. */
    cp = g_new_consumer(mygeom);
    /* Attach newly created consumer to given provider. */
    if (g_attach(cp, pp) != 0) {
        g_destroy_consumer(cp);
        return;
    }
    /* Open provider for reading through our consumer. */
    if (g_access(cp, 1, 0, 0) != 0) {
        g_detach(cp);
        g_destroy_consumer(cp);
        return;
    }

    g_topology_unlock();
    /*
     * Read data from provider.
     */
    g_topology_lock();

    /* Disconnect from provider (release access count). */
    g_access(cp, -1, 0, 0);
    /* Detach from provider. */
    g_detach(cp);
    /* Destroy consumer. */
    g_destroy_consumer(cp);
}

like, notice how every failure path cleans up after itself? that's the energy. 🔥

---

💀 ERRORS 💀

possible errors, and yes there's only one on this list so it's lowkey the main character:

• [ELOOP] — the operation creates a topology loop. (you made the geometry ouroboros itself, bestie, and it did not slay 🙈)

---

🦋 SEE ALSO 🦋

geom(4), DECLARE_GEOM_CLASS(9), g_access(9), g_bio(9), g_consumer(9), g_data(9), g_event(9), g_geom(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>. iconic behavior, honestly. 🫶

---

okay and the lil sign-off at the bottom of the page says this came from Debian, dated January 16, 2004, and it lives in section G_ATTACH(9) — so go forth, attach responsibly, detach dramatically, and hold that topology lock. no cap. 💖✨🎀