1Net::SSH2::File(3)    User Contributed Perl Documentation   Net::SSH2::File(3)
2
3
4

NAME

6       Net::SSH2::File - SSH2 SFTP file object
7

DESCRIPTION

9       An SFTP file object is created by the Net::SSH2::SFTP "open" method.
10
11   read ( buffer, size )
12       Read size bytes from the file into a given buffer.  Returns number of
13       bytes read, or undef on failure.
14
15   write ( buffer )
16       Write buffer to the remote file.
17
18       The "libssh2_sftp_write" function wrapped by this method has a complex
19       and quite difficult (if not impossible at all) to use API. It tries to
20       hide the packet pipelining being done under the hood in order to attain
21       decent throughput.
22
23       Net::SSH2 can not hide that complexity without negatively affecting the
24       transmission speed so it provides just a thin wrapper for that library
25       function.
26
27       An excerpt from "libssh2_sftp_write" manual page follows:
28
29         WRITE AHEAD
30
31         Starting in libssh2 version 1.2.8, the default behavior of libssh2
32         is to create several smaller outgoing packets for all data you pass
33         to this function and it will return a positive number as soon as the
34         first packet is acknowledged from the server.
35
36         This has the effect that sometimes more data has been sent off but
37         isn't acked yet when this function returns, and when this function
38         is subsequently called again to write more data, libssh2 will
39         immediately figure out that the data is already received remotely.
40
41         In most normal situation this should  not cause any problems, but it
42         should be noted that if you've once called libssh2_sftp_write() with
43         data and  it returns short, you  MUST still assume that  the rest of
44         the data  might've been cached  so you need  to make sure  you don't
45         alter that  data and think  that the version  you have in  your next
46         function invoke will be detected or used.
47
48         The reason  for this funny behavior  is that SFTP can  only send 32K
49         data in each packet and it gets all packets acked individually. This
50         means we  cannot use a  simple serial approach  if we want  to reach
51         high performance even on high latency connections. And we want that.
52
53       This is an example of simple file uploading
54
55           use constant BUF_SIZE => 128*1024;
56
57           my $sftp = $ssh2->sftp;
58           open my $fh, '<', '/tmp/doc.txt';
59           my $sf = $sftp->open('doc.txt', O_CREAT|O_WRONLY|O_TRUNC);
60
61           my $buf;
62           while (sysread($fh, $buf, BUF_SIZE)) {
63               while (length $buf) {
64                   my $rc = $sf->write($buf);
65                   if (!defined($rc)) {
66                       $sftp->die_with_error('write error');
67                   }
68                   # Remove transferred data from the buffer.
69                   substr($buf, 0, $rc) = '';
70               }
71           }
72
73   stat
74       Returns file attributes; see Net::SSH2::SFTP::stat.
75
76   setstat ( key, value... )
77       Sets file attributes; see Net::SSH2::SFTP::setstat.
78
79   seek ( offset )
80       Set the file pointer offset.
81
82   tell
83       Returns the current file pointer offset.
84

SEE ALSO

86       Net::SSH2::SFTP.
87
88       Check Net::SFTP::Foreign for a high level, perlish and easy to use SFTP
89       client module. It can work on top of Net::SSH2 via the
90       Net::SFTP::Foreign::Backend::Net_SSH2 backend module.
91

93       Copyright (C) 2005, 2006 by David B. Robins <dbrobins@cpan.org>;
94
95       Copyright (C) 2015 by Salvador Fandiño <sfandino@yahoo.com>;
96
97       All rights reserved.
98
99       This library is free software; you can redistribute it and/or modify it
100       under the same terms as Perl itself, either Perl version 5.8.0 or, at
101       your option, any later version of Perl 5 you may have available.
102
103       The documentation for this package contains and excerpt from libssh2
104       manual pages. You can consult the license of the libssh2 project for
105       the conditions regulating the copyright of that part.
106
107
108
109perl v5.38.0                      2023-07-21                Net::SSH2::File(3)
Impressum