G_ACCESS(9)

💖 G_ACCESS(9) 💖

okay bestie, gather round, because today we're talking about g_access — a page straight out of the Kernel Developer's Manual, and it's literally the bouncer at the club that is your GEOM provider. let's get into it ✨

---

🌸 NAME 🌸

g_access — control access to GEOM consumers and their providers

---

✨ SYNOPSIS ✨

#include <geom/geom.h>

int
g_access(struct g_consumer *cp, int dcr, int dcw, int dce);

---

🦋 DESCRIPTION 🦋

so the g_access() function is your girl for opening, closing, and generally messing with access to the provider that's attached to the consumer cp you handed her. she's flexible like that 💅

the three args — dcr, dcw, and dce — are the relative changes to the read, write, and exclusive access counts. read and write are pretty self-explanatory bestie, like obviously. and exclusive access counts? those deny write access to other interested parties. no sharing, no gatecrashing, periodt. 🔥

also important: a provider's access count is the sum of the access counts of all attached consumers. math! 🧮

and listen — after you attach a consumer to a provider with g_attach(9), you have to call g_access() on that consumer before you start doing any I/O requests. no skipping steps, bestie, that's not the vibe 🙈

---

🎀 RESTRICTIONS/CONDITIONS 🎀

the rules, the non-negotiables, the vibe check:

• the consumer has to be attached to a provider. non-optional.
• the intended change must not result in a negative access count. don't go below zero, it's giving undefined chaos.
• no-operation is not permitted (dcr = dcw = dce = 0). doing nothing is not a flex here.
• the provider's geom must have an access method defined (e.g., gp->access). it needs the method, bestie.
• the topology lock has to be held. hold it. hold it tight. 🫶

---

👑 RETURN VALUES 👑

g_access() returns 0 if everything slayed; otherwise you get an error code back. 😭

and here's a cute lil note: g_access() cannot fail when the arguments dcr, dcw, and dce are less than or equal to 0. so closing down? always safe. iconic behaviour honestly.

---

🌈 EXAMPLES 🌈

okay so here's the whole main-character arc: create a consumer, attach it to a given provider, gain read access, and read the first sector. watch her work:

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

        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. */
        error = g_access(cp, 1, 0, 0);
        if (error != 0) {
                printf("Cannot access provider: %s\n", error);
                g_detach(cp);
                g_destroy_consumer(cp);
                return;
        }

        /*
         * Don't hold topology lock while reading.
         */
        g_topology_unlock();
        ptr = g_read_data(cp, 0, pp->sectorsize, &error);
        if (ptr == NULL)
                printf("Error while reading: %d\n", error);
        /*
         * Do something useful with data.
         */
        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… the cleanup arc alone? chef's kiss. notice how she unlocks the topology lock while reading and locks it right back after? that's the etiquette bestie, don't read while holding the lock 💀

---

💀 ERRORS 💀

possible errors, and yes we're naming names:

• [EPERM] — the function is trying to open a provider with an exclusive access count, but it is already open for writing. awkward!
• [EPERM] — the function is trying to open a provider for writing, but it is already exclusively open. also awkward!

plus: any other error that can be returned by the provider's access method. so like, whatever the provider's method decides to throw at you, that's fair game. 🤷

---

💜 SEE ALSO 💜

go read these next, i'm obsessed:

geom(4), DECLARE_GEOM_CLASS(9), g_attach(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>. thank you for your service, king 🫡

---

and that's the whole page bestie!! this little cutie comes from the Debian side of the world, dated January 16, 2004 — old but gold, fr fr. now go hold that topology lock and slay 💅✨🌸