Provided by: libsys-virt-perl_4.0.0-1_amd64 
NAME
Sys::Virt::Stream - Represent & manage a libvirt stream
DESCRIPTION
The "Sys::Virt::Stream" module represents a stream managed by the virtual machine monitor.
METHODS
my $st Sys::Virt::Stream->new($conn, $flags);
Creates a new data stream, ready for use with a stream based API. The optional $flags parameter can
be used to configure the stream as non-blocking
$st->abort()
Abort I/O on the stream. Either this function or "finish" must be called on any stream which has been
activated
$st->finish()
Complete I/O on the stream. Either this function or "abort" must be called on any stream which has
been activated
$rv = $st->recv($data, $nbytes, $flags=0)
Receive up to $nbytes worth of data, copying into $data. Returns the number of bytes read, or -3 if
hole is reached and $flags contains RECV_STOP_AT_HOLE, or -2 if I/O would block, or -1 on error. The
$flags parameter accepts the following flags:
Sys::Virt::Stream::RECV_STOP_AT_HOLE
If this flag is set, the "recv" function will stop reading from stream if it has reached a hole.
In that case, -3 is returned and "recv_hole" should be called to get the hole size.
$rv = $st->send($data, $nbytes)
Send up to $nbytes worth of data, copying from $data. Returns the number of bytes sent, or -2 if I/O
would block, or -1 on error.
$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 "send_hole". The
optional $flags parameter is currently unused and defaults to zero if omitted.
$st->send_hole($length, $flags=0)
Rather than transmitting empty file space, this method directs the stream target to create $length
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 $flags parameter is currently
unused and defaults to zero if omitted.
$st->recv_all($handler)
Receive all data available from the stream, invoking $handler to process the data. The $handler
parameter must be a function which expects three arguments, the $st 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.
$st->send_all($handler)
Send all data produced by $handler to the stream. The $handler parameter must be a function which
expects three arguments, the $st 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
$st->sparse_recv_all($handler, $hole_handler)
Receive all data available from the sparse stream, invoking $handler to process the data. The
$handler parameter must be a function which expects three arguments, the $st 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 $hole_handler is a function which expects two
arguments: the $st stream and a scalar, number describing the size of the hole in the stream (in
bytes). The $hole_handler is expected to return a non-negative number on success (usually 0) and a
negative number (usually -1) otherwise.
$st->sparse_send_all($handler, $hole_handler, $skip_handler)
Send all data produced by $handler to the stream. The $handler parameter must be a function which
expects three arguments, the $st 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 $hole_handler is a function expecting just one argument $st and
returning an array of two elements ($in_data, $section_len) where $in_data has zero or non-zero value
if underlying file is in a hole or data section respectively. The $section_len then is the number of
remaining bytes in the current section in the underlying file. Finally, the third $skip_handler is a
function expecting two arguments $st and $length which moves cursor in the underlying file for
$length bytes. The $skip_handler is expected to return a non-negative number on success (usually 0)
and a negative number (usually -1) otherwise.
$st->add_callback($events, $coderef)
Register a callback to be invoked whenever the stream has one or more events from $events mask set.
The $coderef must be a subroutine that expects 2 parameters, the original $st object and the new
$events mask
$st->update_callback($events)
Change the event mask for a previously registered callback to $events
$st->remove_callback();
Remove a previously registered callback
CONSTANTS
Sys::Virt::Stream::NONBLOCK
Create a stream which will not block when performing I/O
Sys::Virt::Stream::EVENT_READABLE
The stream has data available for read without blocking
Sys::Virt::Stream::EVENT_WRITABLE
The stream has ability to write data without blocking
Sys::Virt::Stream::EVENT_ERROR
An error occurred on the stream
Sys::Virt::Stream::EVENT_HANGUP
The remote end of the stream closed
AUTHORS
Daniel P. Berrange <berrange@redhat.com>
COPYRIGHT
Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange
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.
SEE ALSO
Sys::Virt, Sys::Virt::Error, "http://libvirt.org"
perl v5.26.1 2018-01-24 Sys::Virt::Stream(3pm)