/ 
Net-LibSSH-0.002
/ Net::LibSSH::Channel

NAME

Net::LibSSH::Channel - SSH exec channel for Net::LibSSH

VERSION

version 0.002

SYNOPSIS

my $ch = $ssh->channel;

$ch->exec('uname -r') or die "exec failed";
my $out = $ch->read;
print "kernel: $out";
print "exit: ", $ch->exit_status, "\n";
$ch->close;

DESCRIPTION

Net::LibSSH::Channel represents an open SSH session channel. Instances are created via "channel" in Net::LibSSH and must not be constructed directly.

A channel runs one command per lifetime. After exec completes you can read stdout and stderr independently, then retrieve the exit status. Call close (or let the object go out of scope) to free the underlying libssh channel.

METHODS

exec($command)

$ch->exec('uname -r') or die "exec failed";

Execute a command on the remote host. Returns 1 on success, 0 on failure. Must be called exactly once per channel.

read([$length [, $is_stderr]])

my $stdout = $ch->read;         # slurp all stdout until EOF
my $chunk  = $ch->read(4096);   # read up to 4096 bytes from stdout
my $stderr = $ch->read(-1, 1);  # slurp all stderr

Read output from the channel. Without arguments (or with -1 length), reads until the remote side closes the stream. With a positive $length, reads at most that many bytes. Pass a true $is_stderr as the second argument to read from stderr instead of stdout.

Note: Do not pass undef as the length — it evaluates to 0 and reads nothing. Use -1 or omit the argument entirely to slurp all output.

Returns a string (possibly empty). Never throws.

write($data)

my $n = $ch->write("input\n");

Write $data to the channel's standard input. Returns the number of bytes written, or a negative value on error.

send_eof

$ch->send_eof;

Signal end-of-input to the remote command. Call this after all write calls so that commands reading stdin (e.g. cat) know to terminate.

eof

$ch->send_eof;
my $out = $ch->read;
$ch->eof and print "channel closed by remote\n";

Returns true when the remote side has sent EOF on its stdout.

exit_status

my $rc = $ch->exit_status;

Returns the exit status of the executed command. Call this after reading all output; returns -1 until the remote process has exited.

close

$ch->close;

Close the channel and free the underlying libssh resources (send EOF, close, free). Also called automatically when the object is garbage-collected.

SEE ALSO

Net::LibSSH, Net::LibSSH::SFTP

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-net-libssh/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.