Sys::V...:Stream(3pm)

📦
version 12.4.0 · 12 versions
, in epel 10

✨ NAME ✨

Sys::Virt::Stream — Represent & manage a libvirt stream 💖

okay bestie, welcome to the Sys::Virt::Stream(3pm) page from the User Contributed Perl Documentation. This is literally the whole vibe on representing & managing a libvirt stream, and yes, we’re keeping every detail. periodt. ✨

🦋 DESCRIPTION 🦋

The Sys::Virt::Stream module represents a stream managed by the virtual machine monitor. like, that’s the main character right there 👑

💅 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. this one is required, bestie 🫶
  • $st->finish() — complete I/O on the stream. Either this function or abort must be called on any stream which has been activated. also required, no skipping 💅
  • $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> — shoutout to the icon who wrote this 👑

Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange

🎀 LICENSE 🎀

okay legal bestie moment, here’s the license text verbatim:

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 🔥

that’s the whole page, bestie! 💖 This one is from perl v5.40.2, dated 2026-06-08 — stream responsibly and slay ✨👑

📦 where this page comes from