gensio_event(3)

🎀 NAME 🎀

gensio_event — the event handler that catches all the events your gensio throws at you 💖

---

✨ SYNOPSIS ✨

#include <gensio/gensio.h>

typedef int (*gensio_event)(struct gensio *io, void *user_data,
                    int event, int err,
                    unsigned char *buf, gensiods *buflen,
                    const char *const *auxdata);

---

🦋 DESCRIPTION 🦋

okay so bestie, whenever Something Happens on a gensio and the library needs to tell you about it, it calls the gensio_event handler you registered with that gensio. that's the whole vibe. 🌸

what each parameter actually means depends on which event is being reported, but the ones that never change are:

• io — the gensio the event is being reported for. the main character, obviously. 👑
• user_data — the user_data you handed over when you registered the event handler. it's your stuff, coming back to you.
• event — which particular event is being reported.

and now, the events. buckle up. 🫶

---

🔥 GENSIO_EVENT_READ

called when data is read from the I/O device.

• if err is zero, buf points to a data buffer and buflen is the number of bytes available.
• if err is set, buf and buflen are undefined and you should not use them or modify them. err is a standard gensio errno.
• if err is non-zero, you must set the number of bytes consumed in buflen.

heads up: you must disable read if you don't consume all the bytes, or in any other situation where you don't want the read handler called. fr fr.

auxdata, if it's not NULL, may contain info about the message — like whether it's out of band (oob) data. check the docs on your specific gensio for the deets.

also: only one read callback is allowed to run at a time on a gensio. no tag-teaming. 💅

if an error is reported in err, then the gensio will be closed. this is how it reports that the other end closed the connection (GE_REMCLOSE), or that other internal errors happened.

you should always return zero — it used to not matter, but it does now. periodt.

---

🔥 GENSIO_EVENT_WRITE_READY

called when data can be written to the I/O device.

only one write callback is allowed to run at a time on a gensio. same rule as read, bestie.

unlike Unix-like systems, a write handler will be called (if enabled) when the lower layer has an exception. this is necessary because we don't have a separate exception handler coming from the lower layer. but it's actually useful — it lets the write operation return a failure if something has gone wrong.

you should always return zero, it used to not matter, but it does now. ✨

---

🔥 GENSIO_EVENT_NEW_CHANNEL

a new channel has been created by the remote end of the connection. the new channel gensio is in buf and must be cast. info about the channel gets passed in auxdata — see the docs on the particular gensio for details.

• if this returns an error (non-zero), the channel is shut down — though in the future, specific error returns may behave differently.
• you must return GE_NOTSUP if you don't support this event (like you should for all unhandled events).
• all other error returns besides zero and GE_NOTSUP are reserved. don't get creative. 💀

---

🔥 GENSIO_EVENT_SEND_BREAK

got a request from the other end to send a break. telnet client or server.

blocked if gensio read is disabled.

---

🔥 GENSIO_EVENT_AUTH_BEGIN

authorization has begun — the username and service are available, but nothing else.

there are a few special return values from this event:

• GE_AUTHREJECT — fail the connection, but continue to go through the motions. call this if the user was invalid or data wasn't properly provided.
• 0 — authorization has succeeded. no more authentication is required, but the protocol may still go through the motions of the protocol.
• GE_NOTSUP — just continue with authentication.

any other error will terminate the connection. these should generally be things like out of memory and such, NOT authentication failures of any kind. 🌈

certauth only

---

🔥 GENSIO_EVENT_PRECERT_VERIFY

the connection has received a certificate but has not verified it yet. this lets you modify the certificate authority based on certificate information.

return values are the same as GENSIO_EVENT_AUTH_BEGIN.

ssl and certauth

---

🔥 GENSIO_EVENT_POSTCERT_VERIFY

the connection has received a certificate and has verified it. the verification may have failed. this lets you handle your own verification override.

err will be one of the following:

• 0 — on verification success.
• GE_CERTNOTFOUND — if no certificate was found.
• GE_CERTREVOKED — if the certificate was revoked.
• GE_CERTEXPIRED — if the certificate has expired.
• GE_CERTINVALID — for other errors.

any other error will terminate the connection. these should generally be things like out of memory and such, NOT authentication failures of any kind.

auxdata[0] will be an error string (or NULL if none available). make sure to check if auxdata is NULL before indexing auxdata[0]. 🙈

return values are:

• 0 — authentication succeeded (even if an error was reported).
• GE_NOTSUP — continue with the authentication process. password authentication may occur, for instance, if an error was reported.
• GE_AUTHREJECT — fail the authentication. no more authentication will occur.

ssl and certauth

---

🔥 GENSIO_EVENT_PASSWORD_VERIFY

a password has been received from the remote end — it's passed in buf. the callee should validate it. if you're doing 2-factor auth, you should also fetch the 2-factor data with the GENSIO_CONTROL_2FA control and handle that here, too. if this function is called, GENSIO_EVENT_2FA_VERIFY is not called.

the length is passed in *buflen. note that buf is nil terminated one past the length.

return values are:

• 0 — the password verification succeeds.
• GE_NOTSUP — fail the validation, but the connection shutdown will depend on the setting of allow-authfail.
• GE_AUTHREJECT — reject the authorization for some other reason besides failing validation.

any other error will terminate the connection. these should generally be things like out of memory and such, NOT authentication failures of any kind.

certauth only

---

🔥 GENSIO_EVENT_REQUEST_PASSWORD

on the client side of an authorization, the remote end has requested that a password be sent. buf points to a buffer of *buflen bytes to place the password in — you should put the password there and update *buflen to the actual length. 💌

return 0 for success, or any other gensio error to fail the password fetch.

---

🔥 GENSIO_EVENT_REQUEST_2FA

on the client side of an authorization, the remote end has requested two-factor authentication data, but it hasn't been supplied already. buf points to a pointer to a buffer (unsigned char **) that you should return. it should be allocated with the zalloc function of the os_functions in use. *buflen is where to put the size of the buffer. this buffer will be zeroed and freed when done.

return 0 for success, or any other gensio error to fail the 2FA fetch.

---

🔥 GENSIO_EVENT_2FA_VERIFY

a 2-factor auth has been received from the remote end and passed as part of the password transfer. this is only called if the login was validated with a certificate — it's called to handle 2-factor auth with a certificate. the 2fa data is passed in buf. the callee should validate it. the length is passed in *buflen. note that buf is nil terminated one past the length.

return values are:

• 0 — the verification succeeds.
• GE_NOTSUP — fail the validation, but the connection shutdown will depend on the setting of allow-authfail.
• GE_AUTHREJECT — reject the authorization for some other reason besides failing validation.

any other error will terminate the connection. these should generally be things like out of memory and such, NOT authentication failures of any kind.

certauth only

---

🔥 GENSIO_EVENT_PARMLOG

when parsing a gensio string, this gets called if the gensio detects an error in the initial parsing or initial configuration. it's called only during the allocation (str_to_gensio() or equivalent). logging this info makes it way easier for users to figure out what's wrong with their gensio strings. 🧚

the buf parameter contains a pointer to the following structure:

struct gensio_parmlog_data {
    const char *log;
    va_list args;
};

which can be printed with normal vprintf() and the like.

---

🔥 GENSIO_EVENT_WIN_SIZE

the other end of the connection is reporting a window size change. currently only on telnet with RFC1073 enabled.

---

🔥 GENSIO_EVENT_LOG

used to report general logs in gensios while processing. can be called any time the gensio exists.

the buf parameter contains a pointer to the following structure:

struct gensio_log_data {
    const char *log;
    va_list args;
};

which can be printed with normal vprintf() and the like.

---

🌸 SERIAL PORT CONTROLS 🌸

these are controls for serial port settings. they're received on the server side only. it should respond by setting the value (if possible and the value isn't zero) and responding with the current value with gensio_acontrol().

if the server receives a zero value for any of these, it should just report the value and not change anything. no cap.

• GENSIO_EVENT_SER_BAUD
• GENSIO_EVENT_SER_DATASIZE
• GENSIO_EVENT_SER_PARITY
• GENSIO_EVENT_SER_STOPBITS
• GENSIO_EVENT_SER_FLOWCONTROL
• GENSIO_EVENT_SER_IFLOWCONTROL
• GENSIO_EVENT_SER_SBREAK
• GENSIO_EVENT_SER_DTR
• GENSIO_EVENT_SER_RTS

for baud, databits, and stopbits, the value is an integer with the number.

parity values can be:

GENSIO_SER_PARITY_NONE
GENSIO_SER_PARITY_ODD
GENSIO_SER_PARITY_EVEN
GENSIO_SER_PARITY_MARK
GENSIO_SER_PARITY_SPACE

flow control values can be:

GENSIO_SER_FLOWCONTROL_NONE
GENSIO_SER_FLOWCONTROL_XON_XOFF
GENSIO_SER_FLOWCONTROL_RTS_CTS

input flow control values can be:

GENSIO_SER_FLOWCONTROL_DCD
GENSIO_SER_FLOWCONTROL_DTR
GENSIO_SER_FLOWCONTROL_DSR

for values that are on/off (the rest), use the following:

GENSIO_SER_ON
GENSIO_SER_OFF

---

💅 SIGNATURE 💅

GENSIO_EVENT_SER_SIGNATURE is received on the server side only and is a request for the signature. the server should respond by sending the signature with gensio_acontrol(). no value is passed in this case.

---

⭐ STATE FUNCTIONS ⭐

• GENSIO_EVENT_SER_MODEMSTATE_MASK
• GENSIO_EVENT_SER_LINESTATE_MASK

these are received on the server side to request updating the mask of reported values. the server should respond by returning the current mask with the gensio_acontrol() function. the server need not handle all the bits requested by the user. 👑

• GENSIO_EVENT_SER_MODEMSTATE
• GENSIO_EVENT_SER_LINESTATE

okay so on the client side, these events are literally reporting your current modemstate and linestate changes as an unsigned integer 💅 and if you wanna know what each bit actually means, you gotta peek at gensio_acontrol(3) — it's giving all the deets ✨

🎀 OTHER SERIAL PORT CONTROLS 🎀

bestie these are server-only 👑 they come in when the server is being asked to do various operations. The server should just do them, but no response is required — it's a vibe, not a conversation 💁‍♀️ You might notice that break is not here, and that's on purpose: break is handled through the GENSIO_EVENT_SEND_BREAK event, periodt.

• GENSIO_EVENT_SER_FLOW_STATE
• GENSIO_EVENT_SER_FLUSH

🦋 SYNC 🦋

GENSIO_EVENT_SER_SYNC is a special operation that shows up when a TCP sync event is received 📡 It may be received on both sides — so don't be surprised if you see it on client or server. A server should send a break. The client can do literally whatever it wants with the info, because that part is not defined by the RFC2217 specification — it's giving mystery, iykyk 🔥

✨ OTHER EVENTS ✨

Other gensio that are not part of the gensio library proper may have their own events — so if you see something you don't recognize, it might be from a different gensio, no cap 💖

💜 RETURN VALUES 💜

You gotta check the individual events to see what values you should return, bestie 👀 If an event is not handled by the event handler, the handler must return GE_NOTSUP — that's the rule. The only exception is GENSIO_EVENT_READ and GENSIO_EVENT_WRITE_READY, which must be handled, no skips, no excuses, periodt 💅

🌈 SEE ALSO 🌈

• gensio_set_callback(3)
• str_to_gensio_child(3)
• gensio_open_channel(3)
• gensio_open_channel_s(3)
• gensio_acc_str_to_gensio(3)
• str_to_gensio(3)
• gensio_err(3)
• gensio_acontrol(3)

and that's the tea for gensio_event(3) — this page was last updated on 21 Feb 2019, so you know it's got that vintage vibe 💖✨ stay slay, bestie! 🎀