Provided by: libgensio-dev_2.8.2-6.1build1_amd64 
NAME
gensio_control - Perform gensio-specific actions
SYNOPSIS
#include <gensio/gensio.h>
int gensio_control(struct gensio *io, int depth, bool get,
unsigned int option,
char *data, gensiods *datalen);
typedef void (*gensio_control_done)(struct gensio *io, int err,
const char *buf, gensiods len,
void *cb_data);
int gensio_acontrol(struct gensio *io, int depth, bool get,
unsigned int option,
char *data, gensiods datalen,
gensio_control_done done, void *cb_data,
gensio_time *timeout);
int gensio_acontrol_s(struct gensio *io, int depth, bool get,
unsigned int option,
char *data, gensiods *datalen,
gensio_time *timeout);
int gensio_acontrol_s_intr(struct gensio *io, int depth, bool get,
unsigned int option,
char *data, gensiods *datalen,
gensio_time *timeout);
const char *gensio_parity_to_str(unsigned int ival);
int gensio_str_to_parity(char *sval);
const char *gensio_flowcontrol_to_str(unsigned int ival);
int gensio_str_to_flowcontrol(char *sval);
const char *gensio_onoff_to_str(unsigned int ival);
int gensio_str_to_onoff(char *sval);
DESCRIPTION
gensio_control performs a gensio-specific operation on the gensio (if depth is 0) or one
of its children ( depth > 0). If depth is GENSIO_CONTROL_DEPTH_ALL, then call all the
children with the data. GE_NOTSUP error returns from individual gensios are ignored in
that case, but it will stop at the first error besides that. If depth is
GENSIO_CONTROL_DEPTH_FIRST, it will return on the first gensio that doesn't return
GE_NOTSUP. It returns GE_NOTFOUND if nothing handled it.
If you specify a depth >= 0, and depth is greater than the number of gensios in the stack,
this will return GE_NOTFOUND. This way you can know if you reached the bottom of the
stack.
Most controls use normal strings for configuration, a control will be this way unless
othersise specified. Some controls allow binary information to be passed.
If get is GENSIO_CONTROL_GET (true), attempt to fetch the option. You cannot use
GENSIO_CONTROL_DEPTH_ALL with a fetch. To fetch an option, you must pass in data long
enough to hold the output and set datalen to the number of bytes available in data for the
output. It will return the length of the string (like strlen, not including the
terminating nil) or binary data in datalen.
An operation with get set to GENSIO_CONTROL_SET (false) is a set operation, it will set
values or controls in the gensio. For string values, datalen is not used in a put
operation or for determining the length of the input string in data, it must be a nil
terminated string. For binary values, datalen must be provided.
All normal controls fetch data immediately and do not block.
gensio_acontrol does a control that is asynchronous, meaning that it is not finished when
the function returns. If it returns zero, the done callback will be called with the
result when the operation completes. All asynchronous control options start with
GENSIO_ACONTROL_xxx. Asynchronous controls do not allow GENSIO_CONTROL_DEPTH_ALL, they
can only be called on a single gensio in the stack.
gensio_acontrol_s does an asynchronous control, but waits until the operation completes
using an os function waiter.
The timeout values on the acontrol functions is a hint to the code, it may or may not have
any effect. It is not necessarily updated to the remaining time, either. For telnet,
this updates the default time to wait for a result. For serialdev it has no effect, as
those operations are immediate. It is ignored for ipmisol.
A get operation is alway indepotent (it won't change anything, so multiple calls will not
have any effect on the state of the system). A get operation may or may not use
information passed in data, and returns information in the data field.
If the output does not fit in a get operation, datalen is updated to where it would have
been if it had enough bytes (one less than the total number of bytes required for string
controls), but the output in data is truncated (and nil terminated if possible for string
controls). This can be used to probe to see how long a buffer is required by passing in a
zero *datalen, and then allocating *datalen (+ 1 for string gensios) and calling the
function again with that data.
gensio control operations in option depend on the particular gensio. Below some are
documented, but there may be other controls available. See the gensio documentation in
gensio(5) for details.
GENSIO_CONTROL_NODELAY
Set the enable/disable for any NAGLE type algorithms. For put the data should be a string
"1" to disable delay, or "0" to enable delay. Return value from a get is a string "1" or
"0".
GENSIO_CONTROL_STREAMS
Return information about incoming and outgoing streams for the gensio. This is
read(get)-only and returns the value in the data in the form "instream=<n>,ostream=<n>".
Used by SCTP.
GENSIO_CONTROL_SEND_BREAK
Request that a break be sent over the line (primarily for telnet).
GENSIO_CONTROL_GET_PEER_CERT_NAME
Return the object from the certificate from the remote end. This is primarily for SSL and
certauth so the application can validate the certificate's common name, but it can fetch
any object from the certificate.
There are two ways to use this interface: fetch by index or fetch by object type.
To fetch by index, just pass in a number in the data, like "0" and it will fetch the value
at that index.
To fetch by object type, pass in a number and the object type separated by a comma. The
object type to fetch is SN (short name) or LN (long name) descriptor per
/usr/include/openssl/object.h. Like "CN" or "commonName". The index should be one less
than the start search, you should use -1, for instance to fetch the first index.
The data returned is in the form: "<index>,<sn>,<value>". Where sn is the short name.
In fetch by object type mode, there may be more than one of an object in a certificate, so
this interface can handle that. just pass in the index returned by the first into the
second call and it will start after that index. For instance, to fetch the first common
name, do (with error checking removed for clarity):
strcpy(data, "-1,CN");
gensio_control(io, 0, true, data, &len)
Say it returns "3,CN,MyName.org" You would use
strcpy(data, "3,CN");
gensio_control(io, 0, true, data, &len)
to get the next common name, which might be "4,CN,MyName2.org". You get an GE_NOTFOUND at
the end.
Returns GE_NOCERT if there is no remote certificate, GE_CERTINVAL if the passed in object
name is not valid, and GE_NOTFOUND if the object was not available in the certificate.
GENSIO_CONTROL_CERT_AUTH
Set the certificate authority file to the string in data. If it ends in '/', it is
assumed to be a directory, otherwise it is assumed to be a file. This generally must be
done before authorization is done, generally before open or in the
GENSIO_EVENT_PRECERT_VERIFY event (see gensio_event(3) for details).
GENSIO_CONTROL_USERNAME
Get/set the username for the gensio, generally the username sent from the client end on a
certauth gensio. This is always a string.
GENSIO_CONTROL_PASSWORD
Get/set the password for the gensio, generally the password sent from the client end on a
certauth gensio. This is always a string. On the server side this will only be available
in the GENSIO_EVENT_PASSWORD_VERIFY event. and is cleared outside of that.
GENSIO_CONTROL_2FA
Get/set the 2-factor auth data for the gensio, generally the data sent from the client end
on a certauth gensio. This is non-nil terminated binary data, generally. On the server
side this will only be available in the GENSIO_EVENT_PASSWORD_VERIFY event or the
GENSIO_2FA_VERIFY event and is cleared outside of that.
GENSIO_CONTROL_SERVICE
On a client, set the service data passed by the gensio to the server. On a server, et the
service sent from the gensio client, generally available on a certauth server. Returns
GE_DATAMISSING if a service was not sent.
This is a binary control, so arbitrary data can be passed in the service.
GENSIO_CONTROL_CERT
Get the full certificate in text form sent from the other end.
GENSIO_CONTROL_CERT_FINGERPRINT
Get the fingerprint for the certificate from the other end.
GENSIO_CONTROL_ENVIRONMENT
Set the environment pointer for an exec. For pty and stdio connecter gensios. The data
is a pointer to an argv array (char * const envp[])
GENSIO_CONTROL_ARGS
Set the arguments for an exec. For pty and stdio connecter gensios. The data is a
pointer to an argv array (char * const argv[])
GENSIO_CONTROL_MAX_WRITE_PACKET
On a packet gensio, return the maximum packet size that can be sent. Any write of this
amount or less will be sent as a single message that will be delivered as one read on the
other end, or it will not be sent at all (zero-byte send count).
GENSIO_CONTROL_EXIT_CODE
On a stdio connectors and pty gensios, the exit code of the process that ran. This is
only valid after close has completed. An integer string is returned.
GENSIO_CONTROL_KILL_TASK
Attempt to terminate the task. The passed in string is converted (strtol) to an integer,
if if it non-zero, a forced kill (kill -9) is done, otherwise a normal terminate is done.
GENSIO_CONTROL_WAIT_TASK
On a stdio connectors and pty gensios, do a waitpid on the process. If it has closed,
this will return success and the exit code in the string. Otherwise it will return
GE_NOTREADY.
GENSIO_CONTROL_ADD_MCAST
On UDP connections, add a multicast address that the socket will receive packets on.
GENSIO_CONTROL_DEL_MCAST
On UDP connections, delete a multicast address that the socket will receive packets on.
GENSIO_CONTROL_MCAST_LOOP
On UDP connections, sets whether multicast packets sent on the socket will be received by
the same machine. Takes/returns string boolean "true" or "false". Defaults to false.
GENSIO_CONTROL_MCAST_TTL
Sets the multicast time-to-live. Takes/returns a string integer. The default is 1,
meaning multicast stays in the local network. Increasing this value increases the number
of hops over multicast routers a send packet will traverse.
GENSIO_CONTROL_LADDR
Return the local address for the connection. Only for network connections or sound
devices.
For network devices, since a single gensio may have more than one local address, this
control provides a means to tell which one. The data string passed in should be the
string representation of a the number (like created with snprintf()) for the particular
index you want to fetch. If you specify a number larger than the number of open listen
sockets, GE_NOTFOUND is returned. The return data is a string holding the address.
Note that a single fetched string may contain more than one address. These will be
separated by semicolons. In some cases addresses may change dynamically (like with SCTP),
so you get a single set of addresses.
For sound devices, pass in "in" or "out" in the string to get the full card number or name
that uniquely identifies the sound card.
GENSIO_CONTROL_RADDR
Like GENSIO_CONTROL_LADDR but gets the remote addresses on a gensio. The gensio may need
to be open. This is only implemented on bottom-level gensios, like serialdev, network
interfaces, echo, file, ipmisol, etc.
GENSIO_CONTROL_RADDR_BIN
Return the binary remote address for the given gensio. Only implemented for network
gensios and pty.
GENSIO_CONTROL_LPORT
Return the local port for the connection. Only for network connections. This is useful
if you pass in "0" for the port to let the OS chose; you can get the actual port chosen.
GENSIO_CONTROL_CLOSE_OUTPUT
Close writing to the gensio, but leave reading along. This is only for stdio gensios; it
lets you close stdin to the subprogram without affecting the subprogram's stdout.
GENSIO_CONTROL_CONNECT_ADDRESS_STR
Return the address the connection was made to. For SCTP. gensio_raddr_to_str() returns
all the remote addresses in SCTP's current state. This will return the addresses that the
original connectx was done to.
GENSIO_CONTROL_REMOTE_ID
Return some sort of remote id for what is on the other end of the connection. Not
implemented for most gensios, only for getting the pid on a pty and stdio and the file
descriptor on serialdev.
GENSIO_CONTROL_AUX_DATA
Return auxiliary sent on the connection. On certauth, this will be sent to the remote end
and be available for them.
GENSIO_CONTROL_REM_AUX_DATA
Return auxiliary received from the other end of the connection. On certauth, this will be
received from the remote end.
GENSIO_CONTROL_IOD
Used to get the IOD pointer for the gensio as a raw pointer. For gensios that have more
than one IOD, the string you pass in will be a string number representing which IOD, "0"
for the first (stdin), "1" for the second (stdout), and "2" for the third, (stderr).
GENSIO_CONTROL_EXTRAINFO
This enables extra info to be returned on a received UDP packet. If this is set to non-
zero (normal string like "1" passed in), extra fields will be added to the auxdata in
received packets. These field are: "daddr:<address>" with the destination address from
the packet and "ifidx:<n>" with the integer interface index the packet was received on.
GENSIO_CONTROL_ENABLE_OOB
Out of band (OOB) data is disabled by default on all gensios and setting this to non-zero
(normal string like "1" passed in) will enable it. Note that you should only set this on
the gensio you are directly communicating with, it is used between some gensios.
GENSIO_CONTROL_WIN_SIZE
For pty gensios, sets the window size of the virtual window. The value is a string with
four values separated by ":". The first two are the number of rows and number of columns.
The second two are number of horizontal pixels and number of vertical pixels. The pixel
values are currently ignored by windows. pixel values do not have to be given, if there
are less than 4 values, pixels values are ignored and set to zero. datalen is ignored.
GENSIO_CONTROL_START_DIR
For pty and stdio gensios (that start another program), this will cause the new program to
run in the given directory instead of the current directory.
GENSIO_CONTROL_IN_RATE , GENSIO_CONTROL_OUT_RATE
For sound gensios, return the sample rate for the gensio for input or output.
GENSIO_CONTROL_IN_BUFSIZE , GENSIO_CONTROL_OUTBUFSIZE
For sound gensios, return the buffer size in bytes for input our output. The data will be
delivered to upper layer in chunks of this size.
GENSIO_CONTROL_IN_NR_CHANS , GENSIO_CONTROL_OUT_NR_CHANS
For sound gensios, return the number of channels for the interface for input or output.
GENSIO_CONTROL_IN_FORMAT , GENSIO_CONTROL_OUT_FORMAT
For sound gensios, return the format of the user data. Like "float", "int16be", etc.
GENSIO_CONTROL_DRAIN_COUNT
The amount of data left to be transmitted. For sound, this is in frames.
SERIAL PORT CONTROLS
The following set various serial port values.
On the client these set the value or request the value from the other end. When getting
the data value is not used. When setting the data value is a string with a number or
setting. The response in the done callback reports a string with the set value (which may
be different than the requested value) in the same format as the request.
On the server these are used to respond to a client event. The done callback is ignored.
GENSIO_ACONTROL_SER_BAUD
is the baud rate as a number. For instance, setting to "1200" sets 1200 baud. Not all
gensio support all baud rates.
GENSIO_ACONTROL_SER_DATASIZE
is the datasize, a number from "5" to "8". Not all gensio support all data sizes.
GENSIO_ACONTROL_SER_PARITY
sets the parity, one of "none", "odd", "even", "mark" or "space". You can use
gensio_parity_to_str and gensio_str_to_parity to convert between the string and numeric
values. gensio_parity_to_str returns NULL if the number isn't value, gensio_str_to_parity
returns -1 if the string is not valid.
GENSIO_ACONTROL_SER_STOPBITS
sets the number of stop bits, "1", or "2".
GENSIO_ACONTROL_SER_FLOWCONTROL
sets the flow control type, one of "none", "xonxoff", or "rtscts". You can use
gensio_flowcontrol_to_str and gensio_str_to_flowcontrol to convert between the string and
numeric values. gensio_flowcontrol_to_str returns NULL if the number isn't value,
gensio_str_to_flowcontrol returns -1 if the string is not valid.
GENSIO_ACONTROL_SER_IFLOWCONTROL
sets the input flow state, one of "none", "dcd", "dtr", or "dsr". You use the same
conversion functions as GENSIO_ACONTROL_SER_FLOWCONTROL for converting between strings and
integers.
GENSIO_ACONTROL_SER_SBREAK
Enables or disables the break condition on a serial port. One of "on" or "off". You can
use gensio_onoff_to_str and gensio_str_to_onoff to convert between the string and numeric
values. gensio_onoff_to_str returns NULL if the number isn't value, gensio_str_to_onoff
returns -1 if the string is not valid.
GENSIO_ACONTROL_SER_DTR
Enables or disables the DTR line on a serial port. One of "on" or "off". See
GENSIO_ACONTROL_SER_SBREAK for string/integer conversions.
GENSIO_ACONTROL_SER_RTS
Enables or disables the RTS line on a serial port. One of "on" or "off". See
GENSIO_ACONTROL_SER_SBREAK for string/integer conversions.
GENSIO_ACONTROL_SER_CTS
Enables or disables the CTS line on a serial port. One of "on" or "off". ipmisol only.
See GENSIO_ACONTROL_SER_SBREAK for string/integer conversions.
GENSIO_ACONTROL_SER_DCD_DSR
Enables or disables the DCD and DTR lines on a serial port. One of "on" or "off".
ipmisol only. See GENSIO_ACONTROL_SER_SBREAK for string/integer conversions.
GENSIO_ACONTROL_SER_RI
Enables or disables the RI line on a serial port. One of "on" or "off". ipmisol only.
See GENSIO_ACONTROL_SER_SBREAK for string/integer conversions.
GENSIO_ACONTROL_SER_SIGNATURE
Fetches or reports the rfc2217 signature for a serial port. This is an arbitrary string.
telnet only.
SERIAL PORT REPORT MASKS
These set (on the client) the mask used to monitor various lines on a serial ports. The
bits set will be the ones reported in the corresponding events. These are numbers in
strings, you bitwise or the values together.
GENSIO_CONTROL_SER_MODEMSTATE
sets the modem control lines that are reported. Values to or together are:
GENSIO_SER_MODEMSTATE_CTS, GENSIO_SER_MODEMSTATE_DSR, GENSIO_SER_MODEMSTATE_RI,
GENSIO_SER_MODEMSTATE_CD.
GENSIO_CONTROL_SER_LINESTATE
sets the line states (errors) that are reported. Values to or together are:
GENSIO_SER_LINESTATE_DATA_READY, GENSIO_SER_LINESTATE_OVERRUN_ERR,
GENSIO_SER_LINESTATE_PARITY_ERR, GENSIO_SER_LINESTATE_FRAMING_ERR,
GENSIO_SER_LINESTATE_BREAK, GENSIO_SER_LINESTATE_XMIT_HOLD_EMPTY,
GENSIO_SER_LINESTATE_XMIT_SHIFT_EMPTY, GENSIO_SER_LINESTATE_TIMEOUT_ERR.
OTHER SERIAL PORT OPERATIONS
This is a set of other operations that can be performed on a serial port.
GENSIO_CONTROL_SER_FLOWCONTROL_STATE
GENSIO_CONTROL_SER_FLUSH
requests a flush of the input or output queues, values are "recv", "xmit", or "both".
GENSIO_CONTROL_SER_SEND_BREAK
requests a serial break (of arbitrary length) be sent. The value is not used.
RETURN VALUES
Zero is returned on success, or a gensio error on failure.
SEE ALSO
gensio_err(3), gensio(5)
27 Feb 2019 gensio_control(3)