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

       Normal gensio operation is asynchronous callback based.  This serves most programs  fairly
       well,  especially  if  they  are  listening to multiple connections at the same time.  You
       wouldn't want to write a compiler this way, but if  you  are  writing  something  that  is
       driven by external events, this event-driven type of programming works well.  If you think
       about it, if you are 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)
                 ...

       The gensio handling does all this for 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.

       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.  This requires synchronous I/O,
       and it uses this capability.

       gensio_set_sync  sets  up  the  gensio  for  synchronous  I/O.   If you do this, the event
       callback that is 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 are like gensio_read_s and gensio_write_s, but
       they return immediately if an signal interrupt occurs.  On systems without signals,  these
       are the same as gensio_read_s and gensio_write_s.

RETURN VALUES

       Zero is returned on success, or a gensio error on failure.

SEE ALSO

       gensio_err(3), gensio(5)

                                           27 Feb 2019                         gensio_set_sync(3)