--- name: "Sys::Virt::Stream" section: "3pm" platform: "linux" package: "perl-sys-virt" version: "12.7.0-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Sys::Virt::Stream" --- # Sys::Virt::Stream(3pm) Represent & manage a libvirt stream ## 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 \ ## 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"`