1Sys::Virt::Stream(3pm)User Contributed Perl DocumentationSys::Virt::Stream(3pm)
2
3
4

NAME

6       Sys::Virt::Stream - Represent & manage a libvirt stream
7

DESCRIPTION

9       The "Sys::Virt::Stream" module represents a stream managed by the
10       virtual machine monitor.
11

METHODS

13       my $st Sys::Virt::Stream->new($conn, $flags);
14           Creates a new data stream, ready for use with a stream based API.
15           The optional $flags parameter can be used to configure the stream
16           as non-blocking
17
18       $st->abort()
19           Abort I/O on the stream. Either this function or "finish" must be
20           called on any stream which has been activated
21
22       $st->finish()
23           Complete I/O on the stream. Either this function or "abort" must be
24           called on any stream which has been activated
25
26       $rv = $st->recv($data, $nbytes, $flags=0)
27           Receive up to $nbytes worth of data, copying into $data.  Returns
28           the number of bytes read, or -3 if hole is reached and $flags
29           contains RECV_STOP_AT_HOLE, or -2 if I/O would block, or -1 on
30           error. The $flags parameter accepts the following flags:
31
32           Sys::Virt::Stream::RECV_STOP_AT_HOLE
33               If this flag is set, the "recv" function will stop reading from
34               stream if it has reached a hole. In that case, -3 is returned
35               and "recv_hole" should be called to get the hole size.
36
37       $rv = $st->send($data, $nbytes)
38           Send up to $nbytes worth of data, copying from $data.  Returns the
39           number of bytes sent, or -2 if I/O would block, or -1 on error.
40
41       $rv = $st->recv_hole($flags=0)
42           Determine the amount of the empty space (in bytes) to be created in
43           a stream's target file when uploading or downloading sparsely
44           populated files. This is the counterpart to "send_hole". The
45           optional $flags parameter is currently unused and defaults to zero
46           if omitted.
47
48       $st->send_hole($length, $flags=0)
49           Rather than transmitting empty file space, this method directs the
50           stream target to create $length bytes of empty space.  This method
51           would be used when uploading or downloading sparsely populated
52           files to avoid the needless copy of empty file space.  The optional
53           $flags parameter is currently unused and defaults to zero if
54           omitted.
55
56       $st->recv_all($handler)
57           Receive all data available from the stream, invoking $handler to
58           process the data. The $handler parameter must be a function which
59           expects three arguments, the $st stream object, a scalar containing
60           the data received and a data byte count. The function should return
61           the number of bytes processed, or -1 upon error.
62
63       $st->send_all($handler)
64           Send all data produced by $handler to the stream.  The $handler
65           parameter must be a function which expects three arguments, the $st
66           stream object, a scalar which must be filled with data and a
67           maximum data byte count desired. The function should return the
68           number of bytes filled, 0 on end of file, or -1 upon error
69
70       $st->sparse_recv_all($handler, $hole_handler)
71           Receive all data available from the sparse stream, invoking
72           $handler to process the data. The $handler parameter must be a
73           function which expects three arguments, the $st stream object, a
74           scalar containing the data received and a data byte count. The
75           function should return the number of bytes processed, or -1 upon
76           error. The second argument $hole_handler is a function which
77           expects two arguments: the $st stream and a scalar, number
78           describing the size of the hole in the stream (in bytes). The
79           $hole_handler is expected to return a non-negative number on
80           success (usually 0) and a negative number (usually -1) otherwise.
81
82       $st->sparse_send_all($handler, $hole_handler, $skip_handler)
83           Send all data produced by $handler to the stream.  The $handler
84           parameter must be a function which expects three arguments, the $st
85           stream object, a scalar which must be filled with data and a
86           maximum data byte count desired.  The function should return the
87           number of bytes filled, 0 on end of file, or -1 upon error. The
88           second argument $hole_handler is a function expecting just one
89           argument $st and returning an array of two elements ($in_data,
90           $section_len) where $in_data has zero or non-zero value if
91           underlying file is in a hole or data section respectively. The
92           $section_len then is the number of remaining bytes in the current
93           section in the underlying file. Finally, the third $skip_handler is
94           a function expecting two arguments $st and $length which moves
95           cursor in the underlying file for $length bytes. The $skip_handler
96           is expected to return a non-negative number on success (usually 0)
97           and a negative number (usually -1) otherwise.
98
99       $st->add_callback($events, $coderef)
100           Register a callback to be invoked whenever the stream has one or
101           more events from $events mask set. The $coderef must be a
102           subroutine that expects 2 parameters, the original $st object and
103           the new $events mask
104
105       $st->update_callback($events)
106           Change the event mask for a previously registered callback to
107           $events
108
109       $st->remove_callback();
110           Remove a previously registered callback
111

CONSTANTS

113       Sys::Virt::Stream::NONBLOCK
114           Create a stream which will not block when performing I/O
115
116       Sys::Virt::Stream::EVENT_READABLE
117           The stream has data available for read without blocking
118
119       Sys::Virt::Stream::EVENT_WRITABLE
120           The stream has ability to write data without blocking
121
122       Sys::Virt::Stream::EVENT_ERROR
123           An error occurred on the stream
124
125       Sys::Virt::Stream::EVENT_HANGUP
126           The remote end of the stream closed
127

AUTHORS

129       Daniel P. Berrange <berrange@redhat.com>
130
132       Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2007 Daniel P.
133       Berrange
134

LICENSE

136       This program is free software; you can redistribute it and/or modify it
137       under the terms of either the GNU General Public License as published
138       by the Free Software Foundation (either version 2 of the License, or at
139       your option any later version), or, the Artistic License, as specified
140       in the Perl README file.
141

SEE ALSO

143       Sys::Virt, Sys::Virt::Error, "http://libvirt.org"
144
145
146
147perl v5.38.0                      2023-09-08            Sys::Virt::Stream(3pm)
Impressum