G_ATTACH(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

🦋 G_ATTACH(9) — the kernel dev manual, bestie edition 🦋

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 the two little functions that decide whether a GEOM consumer and a provider are talking to each other or officially giving each other the silent treatment 💅

✨ 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 g_attach() is the matchmaker function 💖 it attaches the given consumer cp to the given provider pp, and by doing that it literally establishes a communication channel between the consumer and the provider. like, they're linked now. that channel is what lets them change access counts and perform I/O operations. it's giving "you two are connected now, go be iconic together" ✨

and g_detach() is the breakup 😭 it detaches the given consumer cp from its corresponding provider, tearing down the communication channel between them. no more channel, no more talking. periodt.

🎀 RESTRICTIONS/CONDITIONS 🎀

g_attach() 🧚

  • the consumer must not already be attached to a provider
  • the operation must not create a topology loop
  • the topology lock has to be held 🔒

g_detach() 🧚

  • the consumer has to be attached
  • the access count has to be 0
  • there must be no active requests
  • the topology lock has to be held 🔒
bestie these are not suggestions, these are the rules — vibe check your state before you call either of these fr fr 💀

⭐ RETURN VALUES ⭐

g_attach() returns 0 if it slayed (i.e. it was successful); otherwise an error code comes back at you. yeah, that's the whole deal.

(also a tiny heads-up: g_detach() is void, so it doesn't hand you a return value — the original page only documents a return value for g_attach() 👑)

🌈 EXAMPLES 🌈

okay so here's the whole little story: create a consumer, attach it to a given provider, gain read access, and clean up. the full character arc 💖

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);
}

notice how every failure path cleans up after itself? that's main character energy, no leaks, no mess 🫶✨

💀 ERRORS 💀

possible errors, aka the ways this can go wrong:

  • [ELOOP] — the operation creates a topology loop 🙈 (yes, the thing the restrictions said not to do)
  • [ENXIO] — the provider got orphaned 😭

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

go read the whole friend group, iykyk 👑

💜 AUTHORS 💜

this manual page was written by Pawel Jakub Dawidek <pjd@FreeBSD.org>. iconic of him honestly 🎀

and that's the page!! this beauty comes from the Debian build, dated October 10, 2020 — so yeah, go forth and attach responsibly, bestie 🌸💅✨

📦 where this page comes from