Net::SFTP(3)

📦

version 0.12 · 2 versions

0.12 · fedora 43 (latest)
0.12 · fedora 44

✨ NAME ✨

okay so bestie, this is Net::SFTP(3) from the User Contributed Perl Documentation, and it's literally the Secure File Transfer Protocol client. That's the whole vibe: Net::SFTP — Secure File Transfer Protocol client. No cap. 🫶

🌈 SYNOPSIS 🌈

use Net::SFTP;
my $sftp = Net::SFTP->new($host);
$sftp->get("foo", "bar");
$sftp->put("bar", "baz");

🦋 DESCRIPTION 🦋

okay so Net::SFTP is a pure-Perl implementation of the Secure File Transfer Protocol (SFTP) — that's file transfer built on top of the SSH2 protocol, fr fr. It uses Net::SSH::Perl to build a secure, encrypted tunnel through which files can be transferred and managed. It provides a subset of the commands listed in the SSH File Transfer Protocol IETF draft, which can be found at http://www.openssh.com/txt/draft-ietf-secsh-filexfer-00.txt. Iconic behavior honestly.

SFTP stands for Secure File Transfer Protocol and is a method of transferring files between machines over a secure, encrypted connection (as opposed to regular FTP, which functions over an insecure connection — not the move). The security in SFTP comes through its integration with SSH, which provides an encrypted transport layer over which the SFTP commands are executed, and over which files can be transferred. The SFTP protocol defines a client and a server; only the client, not the server, is implemented in Net::SFTP. Periodt.

Because it is built upon SSH, SFTP inherits all of the built-in functionality provided by Net::SSH::Perl: encrypted communications between client and server, multiple supported authentication methods (eg. password, public key, etc.). The way that's giving secure tunnel realness 💅.

👑 USAGE 👑

🌟 `Net::SFTP->new($host, %args)` 🌟

Opens a new SFTP connection with a remote host $host, and returns a Net::SFTP object representing that open connection. Main character energy.

%args can contain:

user — The username to use to log in to the remote server. This should be your SSH login, and can be empty, in which case the username is drawn from the user executing the process. See the login method in Net::SSH::Perl for more details. 💖
password — The password to use to log in to the remote server. This should be your SSH password, if you use password authentication in SSH; if you use public key authentication, this argument is unused. See the login method in Net::SSH::Perl for more details. 🔐
debug — If set to a true value, debugging messages will be printed out for both the SSH and SFTP protocols. This automatically turns on the debug parameter in Net::SSH::Perl. The default is false. 🐛
warn — If given a sub ref, the sub is called with $self and any warning message; if set to false, warnings are supressed; otherwise they are output with 'warn' (default). ⚠️
ssh_args — Specifies a reference to a list or hash of named arguments that should be given to the constructor of the Net::SSH::Perl object underlying the Net::SFTP connection. For example, you could use this to set up your authentication identity files, to set a specific cipher for encryption, etc., e.g. "ssh_args => [ cipher => 'aes256-cbc', options =<gt" [ "MACs +hmac-sha1", "HashKnownHosts yes" ] ]>. See the new method in Net::SSH::Perl for more details. ✨

💅 `$sftp->status` 💅

Returns the last remote SFTP status value. Only useful after one of the following methods has failed. Returns SSH2_FX_OK if there is no remote error (e.g. local file not found). In list context, returns a list of (status code, status text from "fx2txt"). If a low-level protocol error or unexpected local error occurs, we die with an error message. dramatic but valid 💀.

🎀 `$sftp->get($remote [, $local [, \&callback ] ])` 🎀

Downloads a file $remote from the remote host. If $local is specified, it is opened/created, and the contents of the remote file $remote are written to $local. In addition, its filesystem attributes (atime, mtime, permissions, etc.) will be set to those of the remote file. obsessed with the consistency.

If get is called in a non-void context, returns the contents of $remote (as well as writing them to $local, if $local is provided. Undef is returned on failure.

$local is optional. If not provided, the contents of the remote file $remote will be either discarded, if get is called in void context, or returned from get if called in a non-void context. Presumably, in the former case, you will use the callback function \&callback to "do something" with the contents of $remote. iykyk.

If \&callback is specified, it should be a reference to a subroutine. The subroutine will be executed at each iteration of the read loop (files are generally read in 8192-byte blocks, although this depends on the server implementation). The callback function will receive as arguments: a Net::SFTP object with an open SFTP connection; the data read from the SFTP server; the offset from the beginning of the file (in bytes); and the total size of the file (in bytes). You can use this mechanism to provide status messages, download progress meters, etc.:

sub callback {
    my($sftp, $data, $offset, $size) = @_;
    print "Read $offset / $size bytes\r";
}

🌸 `$sftp->put($local, $remote [, \&callback ])` 🌸

Uploads a file $local from the local host to the remote host, and saves it as $remote. slay.

If \&callback is specified, it should be a reference to a subroutine. The subroutine will be executed at each iteration of the write loop, directly after the data has been read from the local file. The callback function will receive as arguments: a Net::SFTP object with an open SFTP connection; the data read from $local, generally in 8192-byte chunks;; the offset from the beginning of the file (in bytes); and the total size of the file (in bytes). You can use this mechanism to provide status messages, upload progress meters, etc.:

sub callback {
    my($sftp, $data, $offset, $size) = @_;
    print "Wrote $offset / $size bytes\r";
}

Returns true on success, undef on error.

🦋 `$sftp->ls($remote [, $subref ])` 🦋

Fetches a directory listing of $remote.

If $subref is specified, for each entry in the directory, $subref will be called and given a reference to a hash with three keys: filename, the name of the entry in the directory listing; longname, an entry in a "long" listing like "ls -l"; and a, a Net::SFTP::Attributes object, which contains the file attributes of the entry (atime, mtime, permissions, etc.).

If $subref is not specified, returns a list of directory entries, each of which is a reference to a hash as described in the previous paragraph.

💅 COMMAND METHODS 💅

Okay bestie, so Net::SFTP is not holding out on you — it supports every single command listed in the SFTP version 3 protocol spec. Each one shows up as its own method you can just... call. ✨

There are exactly three exceptions that do NOT get their own method, because they're handled behind the scenes:

SSH_FXP_INIT
SSH_FXP_VERSION
SSH_FXP_READDIR

Those are the only three. Everything else? Yours. 🫶

These are the available command methods:

`$sftp->do_open($path, $flags [, $attrs ])`

Sends the SSH_FXP_OPEN command to open a remote file $path, and hands you back an open handle when it works. If it fails, you get undef. 😭

Heads up, this matters: that "open handle" is not a Perl filehandle, and it is not a file descriptor. It's literally just a marker — a little name tag the client and the server use to agree on which open file they're talking about. That's it. Don't try to print to it. 💀

$flags should be a bitmask of open flags, and you can get those values from Net::SFTP::Constants:

use Net::SFTP::Constants qw( :flags );

$attrs should be a Net::SFTP::Attributes object specifying the initial attributes for the file $path. And if you're just opening the file for reading only, you can totally leave $attrs blank — it'll get initialized to an empty set of attributes. No stress. 🌸

`$sftp->do_read($handle, $offset, $copy_size)`

Sends the SSH_FXP_READ command to read from an open file handle $handle, starting at $offset, and reading at most $copy_size bytes. 📖

Returns a two-element list: the data read from the SFTP server in the first slot, and the status code (if there is one) in the second.

So like, three scenarios, bestie:

Successful read → the status code is undef, and the data is defined and true. 🎉
EOF → the status code is SSH2_FX_EOF, and the data is undef.
Error → a warning gets emitted, the status code holds the error code, and the data is undef. 😭

`$sftp->do_write($handle, $offset, $data)`

Sends the SSH_FXP_WRITE command to write to an open file handle $handle, starting at $offset, and the data you want written lives in $data. ✍️

Returns the status code. Successful write → the status code equals SSH2_FX_OK. Unsuccessful write → a warning gets emitted, and the status code holds the error the server sent back.

`$sftp->do_close($handle)`

Sends the SSH_FXP_CLOSE command to close either an open file or an open directory, identified by $handle — and yes, that's the handle you got back from either do_open or do_opendir. 🚪

Emits a warning if the CLOSE fails.

Returns the status code for the operation. Wanna turn that status code into an actual readable text message? Go peek at the "fx2txt" function in Net::SFTP::Util. 🧚

`$sftp->do_lstat($path)`

`$sftp->do_fstat($handle)`

`$sftp->do_stat($path)`

These three are giving ✨same energy✨ — they all run a stat on a remote file and return the results in a Net::SFTP::Attributes object on success.

On failure, all three return undef, and all three emit a warning. 🙈

do_lstat sends a SSH_FXP_LSTAT command to get file attributes for a named file $path.
do_stat sends a SSH_FXP_STAT command, and the only way it differs from do_lstat is that do_stat follows symbolic links on the server, while do_lstat does not follow symbolic links. 👑
do_fstat sends a SSH_FXP_FSTAT command to get file attributes for an open file handle $handle.

`$sftp->do_setstat($path, $attrs)`

`$sftp->do_fsetstat($handle, $attrs)`

These two are also matching — they both set the file attributes of a remote file. In both cases, $attrs should be a Net::SFTP::Attributes object. 🎀

do_setstat sends a SSH_FXP_SETSTAT command to set file attributes for a remote named file $path to $attrs.
do_fsetstat sends a SSH_FXP_FSETSTAT command to set the attributes of an open file handle $handle to $attrs.

Both methods emit a warning if the operation fails, and both return the status code for the operation. Again, if you want that status code as a text message, look at the "fx2txt" function in Net::SFTP::Util. 💜

`$sftp->do_opendir($path)`

Sends a SSH_FXP_OPENDIR command to open the remote directory $path, and returns an open handle on success. On failure it returns undef. 📂

`$sftp->do_remove($path)`

Sends a SSH_FXP_REMOVE command to remove the remote file $path. 🗑️

Emits a warning if the operation fails.

Returns the status code for the operation. To turn the status code into a text message, take a look at the "fx2txt" function in Net::SFTP::Util.

`$sftp->do_mkdir($path, $attrs)`

Sends a SSH_FXP_MKDIR command to create a remote directory $path, whose attributes should be initialized to $attrs — a Net::SFTP::Attributes object. 🌈

Emits a warning if the operation fails.

Returns the status code for the operation. To turn the status code into a text message, take a look at the "fx2txt" function in Net::SFTP::Util.

`$sftp->do_rmdir($path)`

Sends a SSH_FXP_RMDIR command to remove a remote directory $path. 🧹

Emits a warning if the operation fails.

Returns the status code for the operation. To turn the status code into a text message, take a look at the "fx2txt" function in Net::SFTP::Util.

`$sftp->do_realpath($path)`

Sends a SSH_FXP_REALPATH command to canonicalise $path into an absolute path. This is lowkey the move when you've got paths containing '..' and you want them turned into absolute paths. 🔥

Returns the absolute path on success, undef on failure.

`$sftp->do_rename($old, $new)`

Sends a SSH_FXP_RENAME command to rename $old to $new. ✨

Emits a warning if the operation fails.

Returns the status code for the operation. To turn the status code into a text message, take a look at the "fx2txt" function in Net::SFTP::Util.

🦋 SUPPORT 🦋

Want samples and tutorials? Bestie, go look at the scripts in eg/ in the distribution directory. They're right there. 💖

There's a mailing list for development discussion and usage questions. Heads up though — posting is limited to subscribers only. You can sign up at http://lists.sourceforge.net/lists/listinfo/ssh-sftp-perl-users

And please report all bugs via rt.cpan.org at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=net%3A%3Asftp 🙏

👑 AUTHOR 👑

Current maintainer is David Robins, dbrobins@cpan.org.
Previous maintainer was Dave Rolsky, autarch@urth.org.
Originally written by Benjamin Trott.

📜 COPYRIGHT 📜

Copyright (c) 2001-2003 Benjamin Trott, Copyright (c) 2003-2004 David Rolsky. Copyright (c) David Robins. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module. 🌸

And that's a wrap, babe 🎀 — this page is from perl v5.42.0, dated 2025-07-25. Go forth and SFTP responsibly, no cap. 💅✨

📦 where this page comes from

fedora 43: perl-Net-SFTP 0.12-22.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Net::SFTP(3)

✨ NAME ✨

🌈 SYNOPSIS 🌈

🦋 DESCRIPTION 🦋

👑 USAGE 👑

🌟 Net::SFTP->new($host, %args) 🌟

💅 $sftp->status 💅

🎀 $sftp->get($remote [, $local [, \&callback ] ]) 🎀

🌸 $sftp->put($local, $remote [, \&callback ]) 🌸

🦋 $sftp->ls($remote [, $subref ]) 🦋

💅 COMMAND METHODS 💅

$sftp->do_open($path, $flags [, $attrs ])

$sftp->do_read($handle, $offset, $copy_size)

$sftp->do_write($handle, $offset, $data)

$sftp->do_close($handle)

$sftp->do_lstat($path)

$sftp->do_fstat($handle)

$sftp->do_stat($path)

$sftp->do_setstat($path, $attrs)

$sftp->do_fsetstat($handle, $attrs)

$sftp->do_opendir($path)

$sftp->do_remove($path)

$sftp->do_mkdir($path, $attrs)

$sftp->do_rmdir($path)

$sftp->do_realpath($path)

$sftp->do_rename($old, $new)

🦋 SUPPORT 🦋

👑 AUTHOR 👑

📜 COPYRIGHT 📜

🌟 `Net::SFTP->new($host, %args)` 🌟

💅 `$sftp->status` 💅

🎀 `$sftp->get($remote [, $local [, \&callback ] ])` 🎀

🌸 `$sftp->put($local, $remote [, \&callback ])` 🌸

🦋 `$sftp->ls($remote [, $subref ])` 🦋

`$sftp->do_open($path, $flags [, $attrs ])`

`$sftp->do_read($handle, $offset, $copy_size)`

`$sftp->do_write($handle, $offset, $data)`

`$sftp->do_close($handle)`

`$sftp->do_lstat($path)`

`$sftp->do_fstat($handle)`

`$sftp->do_stat($path)`

`$sftp->do_setstat($path, $attrs)`

`$sftp->do_fsetstat($handle, $attrs)`

`$sftp->do_opendir($path)`

`$sftp->do_remove($path)`

`$sftp->do_mkdir($path, $attrs)`

`$sftp->do_rmdir($path)`

`$sftp->do_realpath($path)`

`$sftp->do_rename($old, $new)`