.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Sys::Virt::Stream 3pm"
.TH Sys::Virt::Stream 3pm 2024-04-21 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Sys::Virt::Stream \- Represent & manage a libvirt stream
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`Sys::Virt::Stream\*(C'\fR module represents a stream managed
by the virtual machine monitor.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "my $st Sys::Virt::Stream\->new($conn, $flags);" 4
.el .IP "my \f(CW$st\fR Sys::Virt::Stream\->new($conn, \f(CW$flags\fR);" 4
.IX Item "my $st Sys::Virt::Stream->new($conn, $flags);"
Creates a new data stream, ready for use with a stream based
API. The optional \f(CW$flags\fR parameter can be used to configure
the stream as non-blocking
.ie n .IP $st\->\fBabort()\fR 4
.el .IP \f(CW$st\fR\->\fBabort()\fR 4
.IX Item "$st->abort()"
Abort I/O on the stream. Either this function or \f(CW\*(C`finish\*(C'\fR must
be called on any stream which has been activated
.ie n .IP $st\->\fBfinish()\fR 4
.el .IP \f(CW$st\fR\->\fBfinish()\fR 4
.IX Item "$st->finish()"
Complete I/O on the stream. Either this function or \f(CW\*(C`abort\*(C'\fR must
be called on any stream which has been activated
.ie n .IP "$rv = $st\->recv($data, $nbytes, $flags=0)" 4
.el .IP "\f(CW$rv\fR = \f(CW$st\fR\->recv($data, \f(CW$nbytes\fR, \f(CW$flags\fR=0)" 4
.IX Item "$rv = $st->recv($data, $nbytes, $flags=0)"
Receive up to \f(CW$nbytes\fR worth of data, copying into \f(CW$data\fR.
Returns the number of bytes read, or \-3 if hole is reached and
\&\f(CW$flags\fR contains RECV_STOP_AT_HOLE, or \-2 if I/O would block,
or \-1 on error. The \f(CW$flags\fR parameter accepts the following
flags:
.RS 4
.IP Sys::Virt::Stream::RECV_STOP_AT_HOLE 4
.IX Item "Sys::Virt::Stream::RECV_STOP_AT_HOLE"
If this flag is set, the \f(CW\*(C`recv\*(C'\fR function will stop reading from
stream if it has reached a hole. In that case, \-3 is returned and
\&\f(CW\*(C`recv_hole\*(C'\fR should be called to get the hole size.
.RE
.RS 4
.RE
.ie n .IP "$rv = $st\->send($data, $nbytes)" 4
.el .IP "\f(CW$rv\fR = \f(CW$st\fR\->send($data, \f(CW$nbytes\fR)" 4
.IX Item "$rv = $st->send($data, $nbytes)"
Send up to \f(CW$nbytes\fR worth of data, copying from \f(CW$data\fR.
Returns the number of bytes sent, or \-2 if I/O would block,
or \-1 on error.
.ie n .IP "$rv = $st\->recv_hole($flags=0)" 4
.el .IP "\f(CW$rv\fR = \f(CW$st\fR\->recv_hole($flags=0)" 4
.IX Item "$rv = $st->recv_hole($flags=0)"
Determine the amount of the empty space (in bytes) to be created
in a stream's target file when uploading or downloading sparsely
populated files. This is the counterpart to \f(CW\*(C`send_hole\*(C'\fR. The
optional \f(CW$flags\fR parameter is currently unused and defaults to
zero if omitted.
.ie n .IP "$st\->send_hole($length, $flags=0)" 4
.el .IP "\f(CW$st\fR\->send_hole($length, \f(CW$flags\fR=0)" 4
.IX Item "$st->send_hole($length, $flags=0)"
Rather than transmitting empty file space, this method directs
the stream target to create \f(CW$length\fR bytes of empty space.
This method would be used when uploading or downloading sparsely
populated files to avoid the needless copy of empty file space.
The optional \f(CW$flags\fR parameter is currently unused and defaults
to zero if omitted.
.ie n .IP $st\->recv_all($handler) 4
.el .IP \f(CW$st\fR\->recv_all($handler) 4
.IX Item "$st->recv_all($handler)"
Receive all data available from the stream, invoking
\&\f(CW$handler\fR to process the data. The \f(CW$handler\fR
parameter must be a function which expects three
arguments, the \f(CW$st\fR stream object, a scalar containing
the data received and a data byte count. The function
should return the number of bytes processed, or \-1
upon error.
.ie n .IP $st\->send_all($handler) 4
.el .IP \f(CW$st\fR\->send_all($handler) 4
.IX Item "$st->send_all($handler)"
Send all data produced by \f(CW$handler\fR to the stream.
The \f(CW$handler\fR parameter must be a function which
expects three arguments, the \f(CW$st\fR stream object, a
scalar which must be filled with data and a maximum
data byte count desired. The function should return
the number of bytes filled, 0 on end of file, or
\&\-1 upon error
.ie n .IP "$st\->sparse_recv_all($handler, $hole_handler)" 4
.el .IP "\f(CW$st\fR\->sparse_recv_all($handler, \f(CW$hole_handler\fR)" 4
.IX Item "$st->sparse_recv_all($handler, $hole_handler)"
Receive all data available from the sparse stream, invoking
\&\f(CW$handler\fR to process the data. The \f(CW$handler\fR parameter must
be a function which expects three arguments, the \f(CW$st\fR stream
object, a scalar containing the data received and a data byte
count. The function should return the number of bytes processed,
or \-1 upon error. The second argument \f(CW$hole_handler\fR is a
function which expects two arguments: the \f(CW$st\fR stream and a
scalar, number describing the size of the hole in the stream (in
bytes). The \f(CW$hole_handler\fR is expected to return a non-negative
number on success (usually 0) and a negative number (usually \-1)
otherwise.
.ie n .IP "$st\->sparse_send_all($handler, $hole_handler, $skip_handler)" 4
.el .IP "\f(CW$st\fR\->sparse_send_all($handler, \f(CW$hole_handler\fR, \f(CW$skip_handler\fR)" 4
.IX Item "$st->sparse_send_all($handler, $hole_handler, $skip_handler)"
Send all data produced by \f(CW$handler\fR to the stream.  The
\&\f(CW$handler\fR parameter must be a function which expects three
arguments, the \f(CW$st\fR stream object, a scalar which must be
filled with data and a maximum data byte count desired.  The
function should return the number of bytes filled, 0 on end of
file, or \-1 upon error. The second argument \f(CW$hole_handler\fR is a
function expecting just one argument \f(CW$st\fR and returning an
array of two elements (\f(CW$in_data\fR, \f(CW$section_len\fR) where
\&\f(CW$in_data\fR has zero or non-zero value if underlying file is in a
hole or data section respectively. The \f(CW$section_len\fR then is the
number of remaining bytes in the current section in the
underlying file. Finally, the third \f(CW$skip_handler\fR is a function
expecting two arguments \f(CW$st\fR and \f(CW$length\fR which moves cursor
in the underlying file for \f(CW$length\fR bytes. The \f(CW$skip_handler\fR
is expected to return a non-negative number on success (usually
0) and a negative number (usually \-1) otherwise.
.ie n .IP "$st\->add_callback($events, $coderef)" 4
.el .IP "\f(CW$st\fR\->add_callback($events, \f(CW$coderef\fR)" 4
.IX Item "$st->add_callback($events, $coderef)"
Register a callback to be invoked whenever the stream has
one or more events from \f(CW$events\fR mask set. The \f(CW$coderef\fR
must be a subroutine that expects 2 parameters, the original
\&\f(CW$st\fR object and the new \f(CW$events\fR mask
.ie n .IP $st\->update_callback($events) 4
.el .IP \f(CW$st\fR\->update_callback($events) 4
.IX Item "$st->update_callback($events)"
Change the event mask for a previously registered
callback to \f(CW$events\fR
.ie n .IP $st\->\fBremove_callback()\fR; 4
.el .IP \f(CW$st\fR\->\fBremove_callback()\fR; 4
.IX Item "$st->remove_callback();"
Remove a previously registered callback
.SH CONSTANTS
.IX Header "CONSTANTS"
.IP Sys::Virt::Stream::NONBLOCK 4
.IX Item "Sys::Virt::Stream::NONBLOCK"
Create a stream which will not block when performing I/O
.IP Sys::Virt::Stream::EVENT_READABLE 4
.IX Item "Sys::Virt::Stream::EVENT_READABLE"
The stream has data available for read without blocking
.IP Sys::Virt::Stream::EVENT_WRITABLE 4
.IX Item "Sys::Virt::Stream::EVENT_WRITABLE"
The stream has ability to write data without blocking
.IP Sys::Virt::Stream::EVENT_ERROR 4
.IX Item "Sys::Virt::Stream::EVENT_ERROR"
An error occurred on the stream
.IP Sys::Virt::Stream::EVENT_HANGUP 4
.IX Item "Sys::Virt::Stream::EVENT_HANGUP"
The remote end of the stream closed
.SH AUTHORS
.IX Header "AUTHORS"
Daniel P. Berrange <berrange@redhat.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2006\-2009 Red Hat
Copyright (C) 2006\-2007 Daniel P. Berrange
.SH LICENSE
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify
it under the terms of either the GNU General Public License as published
by the Free Software Foundation (either version 2 of the License, or at
your option any later version), or, the Artistic License, as specified
in the Perl README file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sys::Virt, Sys::Virt::Error, \f(CW\*(C`http://libvirt.org\*(C'\fR