gensio_set_sync(3)

✨ gensio_set_sync ✨

okay bestie, welcome to the gensio library functions manual 💖 this one's about doing I/O the synchronous way, and honestly? sometimes you just need that. let's get into it.

🎀 NAME 🎀

gensio_set_sync, gensio_clear_sync, gensio_read_s, gensio_write_s — synchronous I/O operations on a gensio 🦋

🌸 SYNOPSIS 🌸

#include <gensio/gensio.h>

int gensio_set_sync(struct gensio *io);

int gensio_clear_sync(struct gensio *io);

int gensio_read_s(struct gensio *io, gensiods *count,
                    void *data, gensiods datalen,
                    struct gensio_time *timeout);

int gensio_read_s_intr(struct gensio *io, gensiods *count,
                    void *data, gensiods datalen,
                    struct gensio_time *timeout);

int gensio_write_s(struct gensio *io, gensiods *count,
                    const void *data, gensiods datalen,
                    struct gensio_time *timeout);

int gensio_write_s_intr(struct gensio *io, gensiods *count,
                    const void *data, gensiods datalen,
                    struct gensio_time *timeout);

💅 DESCRIPTION 💅

so normal gensio behavior is asynchronous callback based, and ngl that serves most programs so well, especially when you're listening to multiple connections at the same time. like, you would NOT want to write a compiler this way, bestie, but if you're writing something that's driven by external events, this event-driven style of programming? it just works. 🫶

think about it — if you're using something like poll, select, etc., you almost always end up with something like:

poll(fds...)
if (fd1 read is set)
   call fd1_read_handler()
if (fd1 write is set)
   call fd1_write_handler()
if (fd2 read is set)
   ...

and the gensio handling does all of this for you. ✨ you just register a handler with the gensio to get the read and write calls. it's more efficient, neater, and you end up with less code. iconic, honestly.

but occasionally you need to do something synchronous with the program execution. for instance, in gtlsshd, if the initial certificate and password verification fails, it uses PAM to handle reading the password from the remote gensio. that requires synchronous I/O, and it uses this capability. periodt. 💅

👑 the functions 👑

• gensio_set_sync — sets up the gensio for synchronous I/O. if you do this, the event callback that's currently registered will no longer receive read and write callbacks. it will receive other callbacks. you must call this before doing any of the synchronous read and write operations. this function will block (while handling normal gensio events) until no callbacks are active. 🧚
• gensio_clear_sync — returns the gensio to asynchronous I/O. the callback will be restored to the one that was set when gensio_set_sync() was called. 🌈
• gensio_read_s — waits for data from the gensio, up to datalen bytes. count (if not NULL) will be updated to the actual number of bytes read. this will wait for any read and will return whatever that read was, even if it is less than datalen. this function waits for the amount of time in timeout. timeout is updated to the amount of time left to wait. if timeout is NULL, wait forever. 😭
• gensio_write_s — writes data to the gensio. count (if not NULL) will be updated to the actual number of bytes written. this function will wait until either the timeout occurs or all the data is written. this function waits for the amount of time in timeout. timeout is updated to the amount of time left to wait. if timeout is NULL, wait forever. 💀
• gensio_read_s_intr and gensio_write_s_intr — like gensio_read_s and gensio_write_s, but they return immediately if a signal interrupt occurs. on systems without signals, these are the same as gensio_read_s and gensio_write_s. 🙈

fr fr, remember: gensio_set_sync is the must before any sync read/write, and NULL timeout means you're waiting forever. no cap.

⭐ RETURN VALUES ⭐

zero is returned on success, or a gensio error on failure. that's it, that's the vibe check. ✨

🦋 SEE ALSO 🦋

gensio_err(3), gensio(5)

and that's the whole page, bestie!! 🎀 this was gensio_set_sync(3) from the Library Functions Manual, dated 27 Feb 2019 — go slay some synchronous I/O, you've got this 💖🌸💅