str_to_gensio(3)

💖 NAME 💖

okay bestie, gather round, because this one is genuinely iconic — it's the whole "make a gensio out of a string" situation. We're talking str_to_gensio, str_to_gensio_child, and gensio_acc_str_to_gensio, and fr fr, all three of them do one job: create a gensio from a string. It's giving Library Functions Manual, it's giving str_to_gensio(3), it's giving main character energy. 💅

✨ SYNOPSIS ✨

First things first, you gotta pull in the header, no cap:

#include <gensio/gensio.h>

Then here's the whole lineup of functions, exactly as they live in the wild:

int str_to_gensio(const char *str,
                    struct gensio_os_funcs *o,
                    gensio_event cb, void *user_data,
                    struct gensio **io);

int str_to_gensio_child(struct gensio *child, const char *str,
                    struct gensio_os_funcs *o,
                    gensio_event cb, void *user_data,
                    struct gensio **io);

int gensio_acc_str_to_gensio(struct gensio_accepter *accepter,
                    const char *str, struct gensio_os_funcs *o,
                    gensio_event cb, void *user_data,
                    struct gensio **io);

int gensio_terminal_alloc(const char *gensiotype,
                    const void *gdata,
                    const char * const args[],
                    struct gensio_os_funcs *o,
                    gensio_event cb, void *user_data,
                    struct gensio **new_gensio);

int gensio_filter_alloc(const char *gensiotype,
                    struct gensio *child,
                    const char * const args[],
                    struct gensio_os_funcs *o,
                    gensio_event cb, void *user_data,
                    struct gensio **new_gensio);

🦋 DESCRIPTION 🦋

So str_to_gensio allocates a new gensio stack based upon the given string str. That's it, that's the whole vibe. 🎀

str_to_gensio_child is the little sibling situation: it allocates a partial gensio stack and stacks it on top of the given child. Now listen, important lore: if the child is already open, you should use gesnio_open_nochild() to open just this gensio. (Yes, that's spelled exactly like that in the source, we don't question the ancestors.) Also, heads up: this one can only be used to allocate filter gensios. Periodt.

gensio_acc_str_to_gensio is the accepter-flavored one — it allocates a gensio based upon the given accepter. The availability and use of this varies from gensio to gensio, iykyk, but lowkey the flex is that it can be used on UDP to create a gensio that uses the UDP ports that the accepter owns. The details are ✨specific✨:

• This will come from the first address/port that the accepter is on for TCP and UDP.
• It will bind to all the address/ports for SCTP.

And to use it, you must specify a string that exactly matches the layers of the accepter. For instance, if the accepter is "telnet,ssl(CA=x1,key=x2,cert=x3),sctp,3095", then the string must be in the form "telnet,ssl(CA=x2),sctp,otherserver,3820". The layers are exactly the same, but you can vary the options to the layers. 🫶

🌈 Direct Allocation 🌈

If you wanna directly allocation gensios (yes, that's the original phrasing, we're keeping it, it ate), you can use gensio_terminal_alloc and gensio_filter_alloc.

A terminal gensio is one at the bottom of the stack. The gdata parameter depends on the particular gensio. For instance:

• For serialdev, it is a string specifying the device and serial parameters.
• For stdio, it is an argv array.

Go see gensio.5 under "Direct Allocation" for the particular gensio to find out what gdata is. 👑

A filter gensio is one that has a child. You can use these two functions to allocate a gensio stack directly, not using a string format. No strings attached, literally.

💜 The Callback Situation 💜

The cb and user_data parameters set a function that will be called when events come in on the gensio.

• user_data is unused by the gensio stack itself — it's there for you, the user, and may be anything the user wishes.
• cb may be NULL before the gensio is opened, but must be set before it is opened.

🚨 bestie, listen: in particular, the cb does not need to be set if other gensios will be stacked on top of it in the future, because the gensios stacked on top will set the cb and user_data values. So don't stress, the stacking handles it. 💅

The new gensio is returned in io. It will be in the closed state. She's allocated but not open, we love a reserved queen. 🧚

🌸 RETURN VALUES 🌸

Zero is returned on success, or a gensio error on failure. That's the whole thing. Zero = slay. Anything else = read the error, bestie. 😭

🔥 SEE ALSO 🔥

Go read these next, they're all part of the same cinematic universe:

• gensio_set_callback(3)
• gensio_err(3)
• gensio(5)

and that's the whole page, babe 💖 This iconic little entry comes to you from the Library Functions Manual, dated 22 Feb 2019, and yes she's still serving str_to_gensio(3) realness. Obsessed. 🎀✨🦋