/ 
Net-LibSSH-0.003
/ Net::LibSSH::SFTP

NAME

Net::LibSSH::SFTP - Optional SFTP session for Net::LibSSH

VERSION

version 0.003

SYNOPSIS

if (my $sftp = $ssh->sftp) {
    my $attr = $sftp->stat('/etc/hostname');
    printf "size=%d mode=%04o\n", $attr->{size}, $attr->{mode} & 07777
        if $attr;
}

DESCRIPTION

Net::LibSSH::SFTP wraps an SFTP session opened over an existing SSH connection. Instances are created via "sftp" in Net::LibSSH.

If the remote server has no SFTP subsystem, "sftp" in Net::LibSSH returns undef instead of throwing — callers should always check the return value before using the object. The same undef, not a croak, is what "sftp" in Net::LibSSH also returns when called again on a session that has already disconnected — see "disconnect" in Net::LibSSH.

Like Net::LibSSH::Channel, an SFTP session keeps the session it was opened on alive on its own: letting the originating $ssh variable go out of scope, assigning undef to it, or reassigning it to something else does not invalidate it. That guarantee is about the Perl variable, not about the session's connection — it does not protect an SFTP session from $ssh->disconnect. Once the originating session has disconnected, stat croaks with "Net::LibSSH::SFTP::stat: session was disconnected" instead of returning a result. Simply dropping the SFTP object after disconnect — letting it go out of scope, or assigning undef to it — is safe; there is no close method that needs to be called first.

METHODS

stat($path)

my $attr = $sftp->stat('/etc/hostname');
if ($attr) {
    printf "size=%d  uid=%d  mode=%04o\n",
        $attr->{size}, $attr->{uid}, $attr->{mode} & 07777;
}

Returns a hashref describing the remote path, or undef if the path does not exist or cannot be accessed.

Croaks if the session this SFTP object belongs to has been disconnected — see "disconnect" in Net::LibSSH.

Hashref keys:

name

The filename component of the path (or the full path if the server did not return a name).

size

File size in bytes.

uid, gid

Numeric user and group IDs.

mode

Full Unix mode word (type bits + permission bits). Use $attr-{mode} & 07777> to extract just the permission bits.

atime, mtime

Access and modification times as Unix epoch seconds. Uses 64-bit timestamps when available (libssh >= 0.9).

SEE ALSO

Net::LibSSH, Net::LibSSH::Channel

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) 2026 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.