Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
gensio_set_sync(3)	   Library Functions Manual	    gensio_set_sync(3)

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 al-
       most 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 func-
       tion  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 oc-
       curs.  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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gensio_set_sync&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help