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

FreeBSD Manual Pages

  
 
  

home | help
iv_fd_pump(3)		  ivykis programmer's manual		 iv_fd_pump(3)

NAME
       IV_FD_PUMP_INIT,	 iv_fd_pump_init, iv_fd_pump_destroy, iv_fd_pump_pump,
       iv_fd_pump_is_done - pump data between file descriptors

SYNOPSIS
       #include	<iv_fd_pump.h>

       struct iv_fd_pump {
	       int	       from_fd;
	       int	       to_fd;
	       void	       *cookie;
	       void	       (*set_bands)(void *cookie, int pollin, int pollout);
	       unsigned	int    flags;
       };

       void IV_FD_PUMP_INIT(struct iv_fd_pump *this);
       void iv_fd_pump_init(struct iv_fd_pump *this);
       void iv_fd_pump_destroy(struct iv_fd_pump *this);
       int iv_fd_pump_pump(struct iv_fd_pump *this);
       int iv_fd_pump_is_done(const struct iv_fd_pump *this);

DESCRIPTION
       iv_fd_pump provides a way for moving data between two file descriptors.

       To set up iv_fd_pump for	moving data, call IV_FD_PUMP_INIT on a	struct
       iv_fd_pump   object,   fill   in	  the  ->from_fd,  ->to_fd,  ->cookie,
       ->set_bands and ->flags members,	and then call iv_fd_pump_init  on  the
       object.

       Conversely,  to destroy a struct	iv_fd_pump object, call	iv_fd_pump_de-
       stroy.  There are no restrictions on when this function can be called.

       A call to iv_fd_pump_pump will attempt to move data from	 ->from_fd  to
       ->to_fd	via  an	 internal buffer associated with the struct iv_fd_pump
       object.

       During	 calls	  to	iv_fd_pump_init,    iv_fd_pump_destroy	   and
       iv_fd_pump_pump,	 the callback function specified by ->set_bands	may be
       invoked (with ->cookie as its first argument), by which iv_fd_pump  in-
       dicates	under  which circumstances it wishes for future	invocations of
       iv_fd_pump_pump to be done.

       If the pollin argument to ->set_bands is	true, there is space  left  in
       the  internal buffer (and we have not yet seen an end-of-file condition
       on input), and so you should call iv_fd_pump_pump again when there is a
       POLLIN condition	on ->from_fd.

       If  the	pollout	 argument to ->set_bands is true, there	is data	in the
       internal	buffer that could not all be transferred to  ->to_fd,  and  so
       you should call iv_fd_pump_pump again when there	is a POLLOUT condition
       on ->to_fd.

       If IV_FD_PUMP_FLAG_RELAY_EOF is set in  ->flags,	 iv_fd_pump_pump  will
       call  shutdown(2)  on  ->to_fd with SHUT_WR as its second argument upon
       seeing an end-of-file condition on ->from_fd (but only after  all  data
       from the	internal buffer	has been drained into ->to_fd first).

       iv_fd_pump_pump	will  return -1	if there was an	error, 0 if we're done
       pumping data (meaning that an end-of-file condition was seen on the in-
       put  file  descriptor and that all data in the internal buffer has been
       drained into the	output file descriptor), or 1 if there	is  more  data
       left to be pumped.

       iv_fd_pump_is_done will return a	true value if iv_fd_pump_pump has pre-
       viously returned	0, otherwise it	will return false.

       Internally, iv_fd_pump_pump will	use splice(2) if it is available, oth-
       erwise it will fall back	to read(2) and write(2).

SEE ALSO
       ivykis(3), splice(2)

ivykis				  2012-06-05			 iv_fd_pump(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IV_FD_PUMP_INIT&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help