gensio_close(3)

💖 NAME 💖

gensio_close, gensio_close_s, gensio_disable, gensio_free — the girlies that stop and/or free a gensio that's open 🫶

✨ SYNOPSIS ✨

First things first bestie, you gotta pull in the header:

#include <gensio/gensio.h>

typedef void (*gensio_done)(struct gensio *io, void *close_data);

int gensio_close(struct gensio *io, gensio_done close_done,
                    void *close_data);

int gensio_close_s(struct gensio *io);

void gensio_disable(struct gensio *io);

void gensio_free(struct gensio *io);

🌸 DESCRIPTION 🌸

gensio_close — the gentle shutdown 💅

Okay so gensio_close closes an open gensio. But here's the tea: the close operation is not complete until close_done() gets called. No cap. It shuts down internal file descriptors and all that, but it does not free the gensio — she's still there, just not doing anything.

If your gensio is a connecting one, you can generally re-open it. Slay, recycling. ♻️

Now for the spicy part: if you gensio_close before an open done is reported, the results are undefined — mostly like, whether the open done even gets called at all. And if the open done does get called, it will be called before the close done. Order matters, bestie.

gensio_close_s — the synchronous one 😳

gensio_close_s is like gensio_close, but it blocks until the operation is complete.

🚨 BE VERY CAREFUL WITH THIS FUNCTION. Do not call it from a callback, because it waits until all operations on the gensio are done, and they won't be done until the callback returns. If you do this, you will deadlock. That's it, that's the whole warning. Don't do it. 🙈

gensio_disable — the nuclear-ish option 💀

gensio_disable disables operation of the gensio so that closing will not result in any data being transmitted.

🔥 THIS IS FOR EXTREMELY LIMITED USE.

It will not close file descriptors nor disable I/O, necessarily — but it will put the gensio stack into a state where freeing will not result in any transmission of data to the other end.

You MUST be in a state where no callbacks are running or can run. Not "should", must. 👑

Why does this even exist? It's primarily to allow a close of something like an SSL connection after a fork. Because if you didn't have this, the normal close in the one fork would shut down the SSL connection for the other fork too. Rude. 😭 See gensio(5) for details on forking — iykyk.

gensio_free — the real goodbye 🦋

gensio_free frees the data associated with the gensio. And if it's open? Well, the gensio gets closed. Two birds, one iconique function.

But wait — if you call gensio_free after gensio_close but before the close_done callback is called, then whether close_done gets called is undefined. So like, maybe? Maybe not? Nobody knows. ✨

🌈 RETURN VALUES 🌈

• 0 on success 💚
• a gensio error on failure 😭

🎀 SEE ALSO 🎀

• gensio_err(3)
• gensio(5)

Ok that's the whole page bestie, you're basically a gensio expert now 💅✨ This was gensio_close(3) from the Library Functions Manual, dated 27 Feb 2019. Go forth and close responsibly 🫶