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);

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.

       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.   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.

   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 auxilliary 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  auxilliary  received from the other end of the connection.  On certauth, this will
       be received from the remote end.

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)