Net::SSH2::Channel(3pm)

1Net::SSH2::Channel(3) User Contributed Perl DocumentationNet::SSH2::Channel(3)
2
3
4

NAME

6       Net::SSH2::Channel - SSH2 channel object
7

SYNOPSIS

9         my $chan = $ssh2->channel()
10           or $ssh2->die_with_error;
11
12         $chan->exec("ls -ld /usr/local/libssh2*")
13           or $ssh2->die_with_error;
14
15         $chan->send_eof;
16
17         while (<$chan>) {
18           print "line read: $_";
19         }
20
21         print "exit status: " . $chan->exit_status . "\n";
22

DESCRIPTION

24       A channel object is created by the Net::SSH2 "channel" method.  As well
25       as being an object, it is also a tied filehandle.
26
27   setenv ( key, value ... )
28       Sets remote environment variables. Note that most servers do not allow
29       environment variables to be freely set.
30
31       Pass in a list of keys and values with the values to set.
32
33       It returns a true value if all the given environment variables were
34       correctly set.
35
36   blocking ( flag )
37       Enable or disable blocking.
38
39       Note that this is currently implemented in libssh2 by setting a per-
40       session flag. It's equivalent to Net::SSH2::blocking.
41
42   eof
43       Returns true if the remote server sent an EOF.
44
45   send_eof
46       Sends an EOF to the remote side.
47
48       After an EOF has been sent, no more data may be sent to the remote
49       process "STDIN" channel.
50
51       Note that if a PTY was requested for the channel, the EOF may be
52       ignored by the remote server. See "pty".
53
54   close
55       Close the channel (happens automatically on object destruction).
56
57   wait_closed
58       Wait for a remote close event.
59
60       In order to avoid a bug in libssh2 this method discards any unread data
61       queued in the channel.
62
63   exit_status
64       Returns the channel's program exit status.
65
66       This method blocks until the remote side closes the channel.
67
68   pty ( terminal [, modes [, width [, height ]]] )
69       Request a terminal on a channel.
70
71       "terminal" is the type of emulation (e.g. vt102, ansi, etc...).
72
73       "modes" are the terminal mode modifiers, for instance:
74
75           $c->pty('vt100', { echo => 0, vintr => ord('k') });
76
77       The list of acceptable mode modifiers is available from the SSH
78       Connection Protocol RFC (RFC4254
79       <https://tools.ietf.org/html/rfc4254#section-8>).
80
81       If provided, "width" and "height" are the width and height in
82       characters (defaults to 80x24); if negative their absolute values
83       specify width and height in pixels.
84
85   pty_size ( width, height )
86       Request a terminal size change on a channel. "width" and "height" are
87       the width and height in characters; if negative their absolute values
88       specify width and height in pixels.
89
90   ext_data ( mode )
91       Set extended data handling mode:
92
93       normal (default)
94           Keep data in separate channels; "STDERR" is read separately.
95
96       ignore
97           Ignore all extended data.
98
99       merge
100           Merge into the regular channel.
101
102   process ( request, message )
103       Start a process on the channel.  See also shell, exec, subsystem.
104
105       Note that only one invocation of "process" or any of the shortcuts
106       "shell", "exec" or "subsystem" is allowed per channel. In order to run
107       several commands, shells or/and subsystems, a new "Channel" instance
108       must be used for every one.
109
110       Alternatively, it is also possible to launch a remote shell (using
111       shell) and simulate the user interaction printing commands to its
112       "stdin" stream and reading data back from its "stdout" and "stderr".
113       But this approach should be avoided if possible; talking to a shell is
114       difficult and, in general, unreliable.
115
116   shell
117       Start a shell on the remote host (calls "process("shell")").
118
119   exec ( command )
120       Execute the command on the remote host (calls "process("exec",
121       command)").
122
123       Note that the given command is parsed by the remote shell; it should be
124       properly quoted, specially when passing data from untrusted sources.
125
126   subsystem ( name )
127       Run subsystem on the remote host (calls "process("subsystem", name)").
128
129   read ( buffer, max_size [, ext ] )
130       Attempts to read up to "max_size" bytes from the channel into "buffer".
131       If "ext" is true, reads from the extended data channel ("STDERR").
132
133       The method returns as soon as some data is available, even if the given
134       size has not been reached.
135
136       Returns number of bytes read or "undef" on failure. Note that 0 is a
137       valid return code.
138
139   read2 ( [max_size] )
140       Attempts to read from both the ordinary (stdout) and the extended
141       (stderr) channel streams.
142
143       Returns two scalars with the data read both from stdout and stderr. It
144       returns as soon as some data is available and any of the returned
145       values may be an empty string.
146
147       When some error happens it returns the empty list.
148
149       Example:
150
151         my ($out, $err) = ('', '');
152         while (!$channel->eof) {
153             if (my ($o, $e) = $channel->read2) {
154                 $out .= $o;
155                 $err .= $e;
156             }
157             else {
158                 $ssh2->die_with_error;
159             }
160         }
161         print "STDOUT:\n$out\nSTDERR:\n$err\n";
162
163   readline ( [ext [, eol ] ] )
164       Reads the next line from the selected stream ("ext" defaults to 0:
165       stdout).
166
167       $/ is used as the end of line marker when "eol" is "undef".
168
169       In list context reads and returns all the remaining lines until some
170       read error happens or the remote side sends an eof.
171
172       Note that this method is only safe when the complementary stream (e.g.
173       "!ext") is guaranteed to not generate data or when "ext_data" has been
174       used to discard or merge it; otherwise it may hang. This is a
175       limitation of libssh2 that hopefully would be removed in a future
176       release, in the meantime you are advised to use read2 instead.
177
178   getc( [ext] )
179       Reads and returns the next character from the selected stream.
180
181       Returns "undef" on error.
182
183       Note that due to some libssh2 quirks, the return value can be the empty
184       string which may indicate an EOF condition (but not always!). See
185       "eof".
186
187   write ( buffer )
188       Send the data in "buffer" through the channel. Returns number of bytes
189       written, undef on failure.
190
191       In versions of this module prior to 0.57, when working in non-blocking
192       mode, the would-block condition was signaled by returning
193       "LIBSSH2_ERROR_EAGAIN" (a negative number) while leaving the session
194       error status unset. From version 0.59, "undef" is returned and the
195       session error status is set to "LIBSSH2_ERROR_EAGAIN" as for any other
196       error.
197
198       In non-blocking mode, if "write" fails with a "LIBSSH2_ERROR_EAGAIN"
199       error, no other operation must be invoked over any object in the same
200       SSH session besides "sock" and blocking_directions.
201
202       Once the socket becomes ready again, the exact same former "write"
203       call, with exactly the same arguments must be invoked.
204
205       Failing to do that would result in a corrupted SSH session. This is a
206       limitation in libssh2.
207
208   flush ( [ ext ] )
209       Discards the received but still unread data on the channel; if "ext" is
210       present and set, discards data on the extended channel. Returns number
211       of bytes discarded, "undef" on error.
212
213   exit_signal
214       Returns the name of exit signal from the remote command.
215
216       In list context returns also the error message and a language tag,
217       though as of libssh2 1.7.0, those values are always undef.
218
219       This method blocks until the remote side closes the channel.
220
221   exit_signal_number
222       Converts the signal name to a signal number using the local mapping
223       (which may be different to the remote one if the operating systems
224       differ).
225
226   window_read
227       Returns the number of bytes which the remote end may send without
228       overflowing the window limit.
229
230       In list context it also returns the number of bytes that are
231       immediately available for read and the size of the initial window.
232
233   window_write
234       Returns the number of bytes which may be safely written to the channel
235       without blocking at the SSH level. In list context it also returns the
236       size of the initial window.
237
238       Note that this method doesn't take into account the TCP connection
239       being used under the hood. Getting a positive integer back from this
240       method does not guarantee that such number of bytes could be written to
241       the channel without blocking the TCP connection.
242
243   receive_window_adjust (adjustment [, force])
244       Adjust the channel receive window by the given "adjustment" bytes.
245
246       If the amount to be adjusted is less than "LIBSSH2_CHANNEL_MINADJUST"
247       and force is false the adjustment amount will be queued for a later
248       packet.
249
250       On success returns the new size of the receive window. On failure it
251       returns "undef".
252

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO