.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "FTPSSL 3"
.TH FTPSSL 3 "2012-05-21" "perl v5.8.8" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::FTPSSL \- A FTP over SSL/TLS class
.SH "VERSION 0.22"
.IX Header "VERSION 0.22"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::FTPSSL;
\&
\&  my $ftps = Net::FTPSSL\->new(\*(Aqftp.yoursecureserver.com\*(Aq, 
\&                              Encryption => EXP_CRYPT,
\&                              Debug => 1) 
\&    or die "Can\*(Aqt open ftp.yoursecureserver.com\en$Net::FTPSSL::ERRSTR";
\&
\&  $ftps\->login(\*(Aqanonymous\*(Aq, \*(Aquser@localhost\*(Aq) 
\&    or die "Can\*(Aqt login: ", $ftps\->last_message();
\&
\&  $ftps\->cwd("/pub") or die "Can\*(Aqt change directory: " . $ftps\->last_message();
\&
\&  $ftps\->get("file") or die "Can\*(Aqt get file: " . $ftps\->last_message();
\&
\&  $ftps\->quit();
.Ve
.PP
Had you included \fICroak => 1\fR as an option to \fInew\fR, you could have left
off the \fIor die\fR checks and your \fIdie\fR messages would be more specific to the
actual problem encountered!
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Net::FTPSSL\*(C'\fR is a class implementing a simple \s-1FTP\s0 client over a Secure
Sockets Layer (\s-1SSL\s0) or Transport Layer Security (\s-1TLS\s0) connection written in
Perl as described in \s-1RFC959\s0 and \s-1RFC2228\s0.  It will use \s-1TLS\s0 by default.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new( \s-1HOST\s0 [, \s-1OPTIONS\s0 ] )" 4
.IX Item "new( HOST [, OPTIONS ] )"
Creates a new \fBNet::FTPSSL\fR object and opens a connection with the
\&\f(CW\*(C`HOST\*(C'\fR. \f(CW\*(C`HOST\*(C'\fR is the address of the \s-1FTPS\s0 server and it's a required
argument. \s-1OPTIONS\s0 are passed in a hash like fashion, using key and value
pairs.  If you wish you can also pass \fI\s-1OPTIONS\s0\fR as a hash reference.
.Sp
If it can't create a new \fBNet::FTPSSL\fR object, it will return \fIundef\fR unless
you set the \fICroak\fR option.  In either case you will find the cause of the
failure in \fB\f(CB$Net::FTPSSL::ERRSTR\fB\fR.
.Sp
\&\f(CW\*(C`OPTIONS\*(C'\fR are:
.Sp
\&\fBEncryption\fR \- The connection can be implicitly (\fB\s-1IMP_CRYPT\s0\fR) encrypted,
explicitly (\fB\s-1EXP_CRYPT\s0\fR) encrypted, or regular \s-1FTP\s0 (\fB\s-1CLR_CRYPT\s0\fR).
In explicit cases the connection begins clear and became encrypted after an
\&\*(L"\s-1AUTH\s0\*(R" command is sent, while implicit starts off encrypted.  For \fB\s-1CLR_CRYPT\s0\fR,
the connection never becomes encrypted.  Default value is \fB\s-1EXP_CRYPT\s0\fR.
.Sp
\&\fBPort\fR \- The \fIport\fR number to connect to on the remote \s-1FTPS\s0 server.  The
default \fIport\fR is 21 for \fB\s-1EXP_CRYPT\s0\fR and \fB\s-1CLR_CRYPT\s0\fR.  But for \fB\s-1IMP_CRYPT\s0\fR
the default \fIport\fR is 990.  You only need to provide a \fIport\fR if you need to
override the default value.
.Sp
\&\fBDataProtLevel\fR \- The level of security on the data channel.  The default is
\&\fB\s-1DATA_PROT_PRIVATE\s0\fR, where the data is also encrypted. \fB\s-1DATA_PROT_CLEAR\s0\fR is
for data sent as clear text.  \fB\s-1DATA_PROT_SAFE\s0\fR and \fB\s-1DATA_PROT_CONFIDENTIAL\s0\fR
are not currently supported.  If \fB\s-1CLR_CRYPT\s0\fR was selected, the data channel
is always \fB\s-1DATA_PROT_CLEAR\s0\fR and can't be overridden.
.Sp
\&\fBuseSSL\fR \- Use this option to connect to the server using \s-1SSL\s0 instead of \s-1TLS\s0.
\&\s-1TLS\s0 is the default encryption type and the more secure of the two protocols.
Set \fBuseSSL => 1\fR to use \s-1SSL\s0.
.Sp
\&\fBPreserveTimestamp\fR \- During all \fIputs\fR and \fIgets\fR, attempt to preserve the
file's timestamp.  By default it will not preserve the timestamps.
.Sp
\&\fBPret\fR \- Set if you are talking to a distributed \s-1FTPS\s0 server like \fIDrFtpd\fR
that needs a \fB\s-1PRET\s0\fR command issued before all calls to \fB\s-1PASV\s0\fR.  You only need
to use this option if the server barfs at the \fB\s-1PRET\s0\fR auto-detect logic.
.Sp
\&\fBTrace\fR \- Turns on/off (1/0) put/get download tracing to \s-1STDERR\s0.  The default
is off.
.Sp
\&\fBDebug\fR \- This turns the debug tracing option on/off. Default is off. (0,1,2)
.Sp
\&\fBDebugLogFile\fR \- Redirects the output of \fBDebug\fR from \fI\s-1STDERR\s0\fR to the
requested error log file name.  This option is ignored unless \fBDebug\fR is also
turned on.  Enforced this way for backwards compatibility.  If \fBDebug\fR is set
to \fB2\fR, the log file will be opened in \fIappend\fR mode instead of creating a
new log file.  This file is closed when \fIquit\fR is called and \fBDebug\fR messages
go back to \fI\s-1STDERR\s0\fR again afterwards.
.Sp
\&\fBCroak\fR \- Force most methods to call \fI\fIcroak()\fI\fR on failure instead of returning
\&\fI\s-1FALSE\s0\fR.  The default is to return \fI\s-1FALSE\s0\fR or \fIundef\fR on failure.  When it
croaks, it will attempt to close the \s-1FTPS\s0 connection as well, preserving the
last message before it attempts to close the connection.  Allowing the server
to know the client is going away.  This will cause \fI\f(CI$Net::FTPSSL::ERRSTR\fI\fR to
be set as well.
.Sp
\&\fBSSL_Client_Certificate\fR \- Expects a reference to a hash.  It's main purpose
is to allow you to use client certificates when talking to your \fI\s-1FTPS\s0\fR server.
Options here apply to the creation of the command channel.  And when a data
channel is needed later, it uses the \fBSSL_reuse_ctx\fR option to reuse the
command channel's context.  See \fI\fIstart_SSL()\fI\fR in \fIIO::Socket::SSL\fR for more
details on this and other options available.  If an option provided here
conflicts with other options we would normally use, the entries in this hash
take precedence.
.Sp
\&\fBBuffer\fR \- This is the block size that \fINet::FTPSSL\fR will use when a transfer
is made. Default value is 10240.
.Sp
\&\fBTimeout\fR \- Set a connection timeout value. Default value is 120.
.Sp
\&\fBLocalAddr\fR \- Local address to use for all socket connections, this argument
will be passed to all IO::Socket::INET calls.
.Sp
\&\fBOverridePASV\fR \- Some \fI\s-1FTPS\s0\fR servers sitting behind a firewall incorrectly
return their local \s-1IP\s0 Address instead of their external \s-1IP\s0 Address used
outside the firewall where the client is.  To use this option to correct this
problem, you must specify the correct host to use for the \fIdata channel\fR
connection.  This should usually match what you provided as the host!
.Sp
\&\fBOverrideHELP\fR \- Some \fI\s-1FTPS\s0\fR servers on encrypted connections incorrectly send
back part of the response to the \fB\s-1HELP\s0\fR command in clear text instead of it all
being encrypted, breaking the command channel connection.  This class calls
\&\fB\s-1HELP\s0\fR internally via \fI\fIsupported()\fI\fR for some conditional logic, making a work
around necessary to be able to talk to such servers.
.Sp
This option supports three distinct modes to support your needs.  You can pass
a reference to an array that lists all the \fB\s-1FTP\s0\fR commands your sever supports,
you can set it to \fB1\fR to say all commands are supported, or set it to \fB0\fR to
say none of the commands are supported.  See \fI\fIsupported()\fI\fR for more details.
.Sp
This option can also be usefull when your server doesn't support the \fI\s-1HELP\s0\fR
command itself and you need to trigger some of the conditional logic.
.Sp
\&\fBSSL_Advanced\fR \- Depreciated, use \fISSL_Client_Certificate\fR instead.  This is
now just an alias for \fISSL_Client_Certificate\fR for backwards compatibility.
If both are used, this option is ignored.
.SH "METHODS"
.IX Header "METHODS"
Most of the methods return \fItrue\fR or \fIfalse\fR, true when the operation was
a success and false when failed. Methods like \fBlist\fR or \fBnlst\fR return an
empty array when they fail.  This behavior can be modified by the \fBCroak\fR
option.
.IP "login( \s-1USER\s0, \s-1PASSWORD\s0 )" 4
.IX Item "login( USER, PASSWORD )"
Use the given information to log into the \s-1FTPS\s0 server.
.IP "\fIquit()\fR" 4
.IX Item "quit()"
This method breaks the connection to the \s-1FTPS\s0 server.  It will also close the
file pointed to by option \fIDebugLogFile\fR.
.IP "force_epsv( [1/2] )" 4
.IX Item "force_epsv( [1/2] )"
Used to force \fB\s-1EPSV\s0\fR instead of \fB\s-1PASV\s0\fR when establishing a data channel.
Once this method is called, it is imposible to swap back to \fB\s-1PASV\s0\fR.  This
method should be called as soon as possible after you log in if \fB\s-1EPSV\s0\fR is
required.
.Sp
It does this by sending "\fB\s-1EPSV\s0 \s-1ALL\s0\fR" to the server.  Afterwards the server
will reject all \fB\s-1EPTR\s0\fR, \fB\s-1PORT\s0\fR and \fB\s-1PASV\s0\fR commands.
.Sp
After "\fB\s-1EPSV\s0 \s-1ALL\s0\fR" is sent, it will attempt to verify your choice of \s-1IP\s0
Protocol to use: \fB1\fR or \fB2\fR (v4 or v6).  The default is \fB1\fR.  It will use
the selected protocol for all future \fB\s-1EPSV\s0\fR calls.  If you need to change which
protocol to use, you may call this function a second time to swap to the other
\&\fB\s-1EPSV\s0\fR Protocol.
.Sp
This method returns true if it succeeds, or false if it fails.
.IP "set_croak( [1/0] )" 4
.IX Item "set_croak( [1/0] )"
Used to turn the \fICroak\fR option on/off after the \fINet::FTPSSL\fR object has been
created.  It returns the previous \fICroak\fR settings before the change is made.
If you don't provide an argument, all it does is return the current setting.
Provided in case the \fICroak\fR option proves to be too restrictive in some cases.
.IP "list( [\s-1DIRECTORY\s0 [, \s-1PATTERN\s0]] )" 4
.IX Item "list( [DIRECTORY [, PATTERN]] )"
This method returns a list of files in a format similar to this: (Server Specific)
.Sp
.Vb 5
\& drwxrwx\-\-\- 1 owner group          512 May 31 11:16 .
\& drwxrwx\-\-\- 1 owner group          512 May 31 11:16 ..
\& drwxrwx\-\-\- 1 owner group          512 Oct 27  2004 foo
\& drwxrwx\-\-\- 1 owner group          512 Oct 27  2004 pub
\& drwxrwx\-\-\- 1 owner group          512 Mar 29 12:09 bar
.Ve
.Sp
If \fI\s-1DIRECTORY\s0\fR is omitted, the method will return the list of the current
directory.
.Sp
If \fI\s-1PATTERN\s0\fR is provided, it would limit the result similar to the unix \fIls\fR
command or the Windows \fIdir\fR command.  The only wild cards supported are
\&\fB*\fR and \fB?\fR.  (Match 0 or more chars.  Or any one char.) So a pattern of
\&\fIf*\fR, \fI?Oo\fR or \fI\s-1FOO\s0\fR would find just \fIfoo\fR from the list above.  Files with
spaces in their name can cause strange results when searching for a pattern.
.IP "nlst( [\s-1DIRECTORY\s0 [, \s-1PATTERN\s0]] )" 4
.IX Item "nlst( [DIRECTORY [, PATTERN]] )"
Same as \f(CW\*(C`list\*(C'\fR but returns the list in this format:
.Sp
.Vb 3
\& foo
\& pub
\& bar
.Ve
.Sp
Spaces in the filename do not cause problems with the \fI\s-1PATTERN\s0\fR with \f(CW\*(C`nlst\*(C'\fR.
Personally, I suggest using nlst instead of list.
.IP "\fIascii()\fR" 4
.IX Item "ascii()"
Sets the file transfer mode to \s-1ASCII\s0.  \fI\s-1CR\s0 \s-1LF\s0\fR transformations will be done.
\&\s-1ASCII\s0 is the default transfer mode.
.IP "\fIbinary()\fR" 4
.IX Item "binary()"
Sets the file transfer mode to binary. No \fI\s-1CR\s0 \s-1LF\s0\fR transformation will be done.
.IP "put( \s-1LOCAL_FILE\s0 [, \s-1REMOTE_FILE\s0 [, \s-1OFFSET\s0]] )" 4
.IX Item "put( LOCAL_FILE [, REMOTE_FILE [, OFFSET]] )"
Stores the \fI\s-1LOCAL_FILE\s0\fR onto the remote ftps server. \fI\s-1LOCAL_FILE\s0\fR may be a
file handle, but in this case \fI\s-1REMOTE_FILE\s0\fR is required.
It returns \fBundef\fR if \fI\fIput()\fI\fR fails.
.Sp
If you provide an \fI\s-1OFFSET\s0\fR, this method assumes you are attempting to
continue with an upload that was aborted earlier.  And it's your responsibility
to verify that it's the same file on the server you tried to upload earlier.  By
providing the \fI\s-1OFFSET\s0\fR, this function will send a \fB\s-1REST\s0\fR command to the \s-1FTPS\s0
Server to skip over that many bytes before it starts writing to the file.  This
method will also skip over the requested \fI\s-1OFFSET\s0\fR after opening the
\&\fI\s-1LOCAL_FILE\s0\fR for reading, but if passed a file handle it will assume you've
already positioned it correctly.  If you provide an \fI\s-1OFFSET\s0\fR of \fB\-1\fR, this
method will calculate the offset for you by issuing a \fI\s-1SIZE\s0\fR command against
the file on the \s-1FTPS\s0 server.  So \fI\s-1REMOTE_FILE\s0\fR must already exist to use
\&\fB\-1\fR, or it's an error. It is also an error to make \fI\s-1OFFSET\s0\fR larger than the
\&\fI\s-1REMOTE_FILE\s0\fR.
.Sp
If the \fI\s-1OFFSET\s0\fR you provide turns out to be smaller than the current size of
\&\fI\s-1REMOVE_FILE\s0\fR, the server will truncate the \fI\s-1REMOTE_FILE\s0\fR to that size before
appending to the end of \fI\s-1REMOTE_FILE\s0\fR.  (This may not be consistent across
all \s-1FTPS\s0 Servers, so don't depend on this feature without testing it first.)
.Sp
If the option \fIPreserveTimestamp\fR was used, and the \s-1FTPS\s0 server supports it,
it will attempt to reset the timestamp on \fI\s-1REMOTE_FILE\s0\fR to the timestamp on
\&\fI\s-1LOCAL_FILE\s0\fR.
.IP "append( \s-1LOCAL_FILE\s0 [, \s-1REMOTE_FILE\s0 [, \s-1OFFSET\s0]] )" 4
.IX Item "append( LOCAL_FILE [, REMOTE_FILE [, OFFSET]] )"
Appends the \fI\s-1LOCAL_FILE\s0\fR onto the \fI\s-1REMOTE_FILE\s0\fR on the ftps server.  If
\&\fI\s-1REMOTE_FILE\s0\fR doesn't exist, the file will be created.  \fI\s-1LOCAL_FILE\s0\fR may be
a file handle, but in this case \fI\s-1REMOTE_FILE\s0\fR is required and \fI\s-1OFFSET\s0\fR is
ignored.  It returns \fBundef\fR if \fI\fIappend()\fI\fR fails.
.Sp
If you provide an \fI\s-1OFFSET\s0\fR, it will skip over that number of bytes in the
\&\fI\s-1LOCAL_FILE\s0\fR except when it was a file handle, but \fBwill not\fR send a \fB\s-1REST\s0\fR
command to the server.  It will just append to the end of \fI\s-1REMOTE_FILE\s0\fR
on the server.  You can also provide an \fI\s-1OFFSET\s0\fR of \fB\-1\fR with the same
limitations as with \fI\fIput()\fI\fR.  If you need the \fB\s-1REST\s0\fR command sent to the
\&\s-1FTPS\s0 server, use \fI\fIput()\fI\fR instead.
.Sp
If the option \fIPreserveTimestamp\fR was used, and the \s-1FTPS\s0 server supports it,
it will attempt to reset the timestamp on \fI\s-1REMOTE_FILE\s0\fR to the timestamp on
\&\fI\s-1LOCAL_FILE\s0\fR.
.IP "uput( \s-1LOCAL_FILE\s0, [\s-1REMOTE_FILE\s0] )" 4
.IX Item "uput( LOCAL_FILE, [REMOTE_FILE] )"
Stores the \fI\s-1LOCAL_FILE\s0\fR onto the remote ftps server. \fI\s-1LOCAL_FILE\s0\fR may be a
file handle, but in this case \fI\s-1REMOTE_FILE\s0\fR is required.  If \fI\s-1REMOTE_FILE\s0\fR
already exists on the ftps server, a unique name is calculated by the server
for use instead.
.Sp
If the file transfer succeeds, this function will return the actual name used
on the remote ftps server.  If it can't figure that out, it will return what
was used for \fI\s-1REMOTE_FILE\s0\fR.  On failure this method will return \fBundef\fR.
.Sp
If the option \fIPreserveTimestamp\fR was used, and the \s-1FTPS\s0 server supports it,
it will attempt to reset the timestamp on the remote file using the file name
being returned by this function to the timestamp on \fI\s-1LOCAL_FILE\s0\fR.  So if the
wrong name is being returned, the wrong file will get it's timestamp updated.
.IP "xput( \s-1LOCAL_FILE\s0, [\s-1REMOTE_FILE\s0, [\s-1PREFIX\s0, [\s-1POSTFIX\s0, [\s-1BODY\s0]]]] )" 4
.IX Item "xput( LOCAL_FILE, [REMOTE_FILE, [PREFIX, [POSTFIX, [BODY]]]] )"
Use when the directory you are dropping \fI\s-1REMOTE_FILE\s0\fR into is monitored by
a file recognizer that might pick the file up before the file transfer has
completed.  So the file is transferred using a temporary name using a naming
convention that the file recognizer will ignore and is guaranteed to be unique.
Once the file transfer successfully completes, it will be \fIrenamed\fR to
\&\fI\s-1REMOTE_FILE\s0\fR for immediate pickup by the file recognizer.  If you requested
to preserve the file's timestamp, this step is done after the file is renamed
and so can't be 100% guaranteed if the file recognizer picks it up first. Since
if it was done before the rename, other more serious problems could crop up if
the resulting timestamp was old enough.
.Sp
On failure this function will attempt to \fIdelete\fR the scratch file for you if
its at all possible.  You will have to talk to your \s-1FTPS\s0 server administrator on
good values for \fI\s-1PREFIX\s0\fR and \fI\s-1POSTFIX\s0\fR if the defaults are no good for you.
.Sp
\&\fB\s-1PREFIX\s0\fR defaults to \fI_tmp.\fR unless you override it.  Set to "" if you need
to suppress the \fI\s-1PREFIX\s0\fR.  This \fI\s-1PREFIX\s0\fR can be a path to another directory
if needed, but that directory must already exist!  Set to \fIundef\fR to keep this
default and you need to change the default for \fI\s-1POSTFIX\s0\fR or \fI\s-1BODY\s0\fR.
.Sp
\&\fB\s-1POSTFIX\s0\fR defaults to \fI.tmp\fR unless you override it.  Set to "" if you need
to suppress the \fI\s-1POSTFIX\s0\fR.  Set to \fIundef\fR to keep this default and you need
to change the default for \fI\s-1BODY\s0\fR.
.Sp
\&\fB\s-1BODY\s0\fR defaults to \fIclient\-name.PID\fR so that you are guaranteed the temp file
will have an unique name on the remote server.  It is strongly recommended that
you don't override this value.
.Sp
So the temp scratch file would be called something like this by default:
\&\fI_tmp.testclient.51243.tmp\fR.
.Sp
As a final note, if \fI\s-1REMOTE_FILE\s0\fR has path information in it's name, the temp
scratch file will have the same directory added to it unless you override the
\&\fI\s-1PREFIX\s0\fR with a different directory to drop the scratch file into.  This avoids
forcing you to change into the requested directory first when you have multiple
files to send out into multiple directories.
.IP "get( \s-1REMOTE_FILE\s0 [, \s-1LOCAL_FILE\s0 [, \s-1OFFSET\s0]] )" 4
.IX Item "get( REMOTE_FILE [, LOCAL_FILE [, OFFSET]] )"
Retrieves the \fI\s-1REMOTE_FILE\s0\fR from the ftps server. \fI\s-1LOCAL_FILE\s0\fR may be a
filename or a file handle.  It returns \fBundef\fR if \fI\fIget()\fI\fR fails.  You don't
usually need to use \fI\s-1OFFSET\s0\fR.
.Sp
If you provide an \fI\s-1OFFSET\s0\fR, this method assumes your are attempting to
continue with a download that was aborted earlier.  And it's your responsibility
to verify that it's the same file you tried to download earlier.  By providing
the \fI\s-1OFFSET\s0\fR, it will send a \fB\s-1REST\s0\fR command to the \s-1FTPS\s0 Server to skip over
that many bytes before it starts downloading the file again.  If you provide an
\&\fI\s-1OFFSET\s0\fR of \fB\-1\fR, this method will calculate the offset for you based on the
size of \fI\s-1LOCAL_FILE\s0\fR using the current transfer mode.  (\fI\s-1ASCII\s0\fR or \fI\s-1BINARY\s0\fR).
It is an error to set it to \fB\-1\fR if the \fI\s-1LOCAL_FILE\s0\fR is a file handle.
.Sp
On the client side of the download, the \fI\s-1OFFSET\s0\fR will do the following:
Open the file and truncate everything after the given \fI\s-1OFFSET\s0\fR.  So if you
give an \fI\s-1OFFSET\s0\fR that is too big, it's an error.  If it's too small, the
file will be truncated to that \fI\s-1OFFSET\s0\fR before appending what's being
downloaded.  If the \fI\s-1LOCAL_FILE\s0\fR is a file handle, it will assume the file
handle has already been positioned to the proper \fI\s-1OFFEST\s0\fR and it will not
perform a truncate.  Instead it will just append to that file handle's
current location.  Just beware that using huge \fI\s-1OFFSET\s0\fRs in \fB\s-1ASCII\s0\fR mode
can be a bit slow if the \fI\s-1LOCAL_FILE\s0\fR needs to be truncated.
.Sp
If the option \fIPreserveTimestamp\fR was used, and the \s-1FTPS\s0 Server supports it,
it will attempt to reset the timestamp on \fI\s-1LOCAL_FILE\s0\fR to the timestamp on
\&\fI\s-1REMOTE_FILE\s0\fR after the download completes.
.IP "xget( \s-1REMOTE_FILE\s0, [\s-1LOCAL_FILE\s0, [\s-1PREFIX\s0, [\s-1POSTFIX\s0, [\s-1BODY\s0]]]] )" 4
.IX Item "xget( REMOTE_FILE, [LOCAL_FILE, [PREFIX, [POSTFIX, [BODY]]]] )"
The inverse of \fIxput\fR, where the file recognizer is on the client side.  The
only other difference being what \fB\s-1BODY\s0\fR defaults to.  It defaults to
\&\fIreverse(testclient).PID\fR.  So your default scratch file would be something
like: \fI_tmp.tneilctset.51243.tmp\fR.
.Sp
Just be aware that in this case \fB\s-1LOCAL_FILE\s0\fR can no longer be a file handle.
.IP "delete( \s-1REMOTE_FILE\s0 )" 4
.IX Item "delete( REMOTE_FILE )"
Deletes the indicated \fI\s-1REMOTE_FILE\s0\fR.
.IP "cwd( \s-1DIR\s0 )" 4
.IX Item "cwd( DIR )"
Attempts to change directory to the directory given in \fI\s-1DIR\s0\fR on the remote
server.
.IP "pwd( )" 4
.IX Item "pwd( )"
Returns the full pathname of the current directory on the remote server.
.IP "cdup( )" 4
.IX Item "cdup( )"
Changes directory to the parent of the current directory on the remote server.
.IP "mkdir( \s-1DIR\s0 )" 4
.IX Item "mkdir( DIR )"
Creates the indicated directory \fI\s-1DIR\s0\fR on the remote server. No recursion at
the moment.
.IP "rmdir( \s-1DIR\s0 )" 4
.IX Item "rmdir( DIR )"
Removes the empty indicated directory \fI\s-1DIR\s0\fR on the remote server. No recursion
at the moment.
.IP "noop( )" 4
.IX Item "noop( )"
It requires no action other than the server send an \s-1OK\s0 reply.
.IP "rename( \s-1OLD\s0, \s-1NEW\s0 )" 4
.IX Item "rename( OLD, NEW )"
Allows you to rename the file on the remote server.
.IP "site( \s-1ARGS\s0 )" 4
.IX Item "site( ARGS )"
Send a \s-1SITE\s0 command to the remote server and wait for a response.
.IP "mfmt( time_str, remote_file ) or _mfmt( timestamp, remote_file )" 4
.IX Item "mfmt( time_str, remote_file ) or _mfmt( timestamp, remote_file )"
Both are boolean functions that attempt to reset the remote file's timestamp on
the \s-1FTPS\s0 server and returns true on success.  The 1st version can call croak on
failure if \fICroak\fR is turned on, while the 2nd version will not do this.  The
other difference between these two functions is the format of the file's
timestamp to use.
.Sp
\&\fItime_str\fR expects the timestamp to be \s-1GMT\s0 time in format \fI\s-1YYYYMMDDHHMMSS\s0\fR.
While \fItimestamp\fR expects to be in the same format as returned by
\&\fI\fIlocaltime()\fI\fR.
.IP "mdtm( remote_file )  or  _mdtm( remote_file )" 4
.IX Item "mdtm( remote_file )  or  _mdtm( remote_file )"
The 1st version returns the file's timestamp as a string in \fI\s-1YYYYMMDDHHMMSS\s0\fR
format using \s-1GMT\s0 time, it will return \fIundef\fR or call croak on failure.
.Sp
The 2nd version returns the file's timestamp in the same format as returned by
\&\fI\fIlocaltime()\fI\fR and will never call croak.
.IP "size( remote_file )" 4
.IX Item "size( remote_file )"
This function will return \fIundef\fR or croak on failure.  Otherwise it will
return the file's size in bytes, which may also be zero bytes! Just be aware
for text files that the size returned may not match the file's actual size after
the file has been downloaded to your system in \fI\s-1ASCII\s0\fR mode.  This is an \s-1OS\s0
specific issue.  It will always match if you are using \fI\s-1BINARY\s0\fR mode.
.Sp
Also \fI\s-1SIZE\s0\fR may return a different size for \fI\s-1ASCII\s0\fR & \fI\s-1BINARY\s0\fR modes.
This issue depends on what \s-1OS\s0 the \s-1FTPS\s0 server is running under.  Should they
be different, the \fI\s-1ASCII\s0\fR size will be the \fI\s-1BINARY\s0\fR size plus the number of
lines in the file.
.IP "quot( \s-1CMD\s0 [,ARGS] )" 4
.IX Item "quot( CMD [,ARGS] )"
Send a command, that \fINet::FTPSSL\fR does not directly support, to the remote
server and wait for a response.  You are responsible for parsing anything
you need from \fI\fImessage()\fI\fR yourself.
.Sp
Returns the most significant digit of the response code.  So it will ignore
the \fBCroak\fR request.
.Sp
\&\fB\s-1WARNING\s0\fR This call should only be used on commands that do not require
data connections.  Misuse of this method can hang the connection if the
internal list of \s-1FTP\s0 commands using a data channel is incomplete.
.IP "ccc( [ DataProtLevel ] )" 4
.IX Item "ccc( [ DataProtLevel ] )"
Sends the clear command channel request to the \s-1FTPS\s0 server.  If you provide the
\&\fIDataProtLevel\fR, it will change it from the current data protection level to
this one before it sends the \fB\s-1CCC\s0\fR command.  After the \fB\s-1CCC\s0\fR command, the
data channel protection level can not be changed again and will always remain
at this setting.  Once you execute the \fB\s-1CCC\s0\fR request, you will have to create
a new \fINet::FTPSSL\fR object to secure the command channel again.  \fIDue
to security concerns it is recommended that you do not use this method.\fR
.Sp
If the version of \fIIO::Socket::SSL\fR you have installed is too old, this
function will not work since \fIstop_SSL\fR won't be defined (like in v1.08).  So 
it is recommended that you be on at least \fIversion 1.18\fR or later if you plan
on using this function.
.IP "supported( \s-1CMD\s0 [,SITE_OPT] )" 4
.IX Item "supported( CMD [,SITE_OPT] )"
Returns \fB\s-1TRUE\s0\fR if the remote server supports the given command.  \fI\s-1CMD\s0\fR must
match exactly.  This function will ignore the \fBCroak\fR request.
.Sp
If the \fI\s-1CMD\s0\fR is \s-1SITE\s0 or \s-1FEAT\s0 and \fI\s-1SITE_OPT\s0\fR is supplied, it will also check
if the specified \fI\s-1SITE_OPT\s0\fR sub-command is supported by that command.  Not
all servers will support the use of \fI\s-1SITE_OPT\s0\fR.
.Sp
It determines if a command is supported by calling \fB\s-1HELP\s0\fR and parses the
results for a match.  And if \fB\s-1FEAT\s0\fR is supported it calls \fB\s-1FEAT\s0\fR and adds
these commands to the \fB\s-1HELP\s0\fR list.  The results are cached so \fB\s-1HELP\s0\fR and
\&\fB\s-1FEAT\s0\fR are only called once.
.Sp
Some rare servers send the \fB\s-1HELP\s0\fR results partially encrypted and partially in
clear text, causing the encrypted channel to break.  In that case you will need
to override this method for things to work correctly with these non-conforming
servers.  See the \fIOverrideHELP\fR option in the constructor for how to do this.
.Sp
Some servers don't support the \fB\s-1HELP\s0\fR command itself!  When this happens, this
method will always return \fB\s-1FALSE\s0\fR unless you set the \fIOverrideHELP\fR option in
the constructor.
.Sp
This method is used internally for conditional logic only when checking if the
following 4 \fI\s-1FTP\s0\fR commands are allowed: \fB\s-1ALLO\s0\fR, \fB\s-1NOOP\s0\fR, \fB\s-1MFMT\s0\fR, and \fB\s-1MDTM\s0\fR.
The \fB\s-1ALLO\s0\fR command is used with all \fIput\fR/\fIget\fR command sequences.  The other
three are not checked that often.
.IP "\fIlast_message()\fR or \fImessage()\fR" 4
.IX Item "last_message() or message()"
Use either one to collect the last response from the \s-1FTPS\s0 server.  This is the
same response printed to \fI\s-1STDERR\s0\fR when Debug is turned on.  It may also contain
any fatal error message encountered.
.Sp
If you couldn't create a \fINet::FTPSSL\fR object, you should get your error
message from \fI\f(CI$Net::FTPSSL::ERRSTR\fI\fR instead.  Be careful since
\&\fI\f(CI$Net::FTPSSL::ERRSTR\fI\fR is shared between instances of \fINet::FTPSSL\fR, while
\&\fImessage\fR & \fIlast_message\fR \fBare not\fR shared between instances!
.IP "last_status_code( )" 4
.IX Item "last_status_code( )"
Returns the one digit status code associated with the last response from the
\&\s-1FTPS\s0 server.  The status is the first digit from the full 3 digit response code.
.Sp
The possible values are exposed via the following \fB7\fR constants:
\&\s-1CMD_INFO\s0, \s-1CMD_OK\s0, \s-1CMD_MORE\s0, \s-1CMD_REJECT\s0, \s-1CMD_ERROR\s0, \s-1CMD_PROTECT\s0 and \s-1CMD_PENDING\s0.
.IP "restart( \s-1OFFSET\s0 )" 4
.IX Item "restart( OFFSET )"
Set the byte offset at which to begin the next data transfer.  \fINet::FTPSSL\fR
simply records this value and uses it during the next data transfer.  For
this reason this method will never return an error, but setting it may cause
subsequent data transfers to fail.
.Sp
I recommend using the \s-1OFFSET\s0 directly in \fI\fIget()\fI\fR, \fI\fIput()\fI\fR, and \fI\fIappend()\fI\fR
instead of using this method.  It was only added to make \fINet::FTPSSL\fR
compatible with \fINet::FTP\fR.  A non-zero offset in those methods will override
what you provide here.  If you call any of the other \fI\fIget()\fI\fR/\fI\fIput()\fI\fR variants
after calling this function, you will get an error.
.Sp
It is \s-1OK\s0 to use an \fI\s-1OFFSET\s0\fR of \fB\-1\fR here to have \fINet::FTPSSL\fR calculate
the correct \fI\s-1OFFSET\s0\fR for you before it get's used.  Just like if you had
provided it directly to the \fI\fIget()\fI\fR, \fI\fIput()\fI\fR, and \fI\fIappend()\fI\fR calls.
.Sp
This \fI\s-1OFFSET\s0\fR will be automatically zeroed out the 1st time it is used.
.IP "set_callback( [cb_func_ref, end_cb_func_ref [, cb_data_ref]] )" 4
.IX Item "set_callback( [cb_func_ref, end_cb_func_ref [, cb_data_ref]] )"
This function allows the user to define a callback function to use whenever a
data channel to the server is open.  If either \fBcb_func_ref\fR or
\&\fBend_cb_func_ref\fR is undefined, it disables the callback functionality, since
both are required for call backs to function properly.
.Sp
The \fBcb_func_ref\fR is a reference to a function to handle processing the
data channel data.  This is a \fIvoid\fR function that can be called multiple
times.  It is called each time a chunk of data is read from or written to the
data channel.
.Sp
The \fBend_cb_func_ref\fR is a reference to a function to handle closing the
callback for this data channel connection.  This function is allowed to return
a string of additional data to process before the data channel is closed.  It
is called only once per command after processing all the data channel data.
.Sp
The \fBcb_data_ref\fR is an optional reference to an \fIarray\fR or \fIhash\fR that the
caller can use to store values between calls to the callback function and the
end callback function.  If you don't need such a work area, it's safe to not
provide one.  The \fINet::FTPSSL\fR class doesn't look at this reference.
.Sp
The callback function must take the following \fB5\fR arguments:
.Sp
.Vb 1
\&   B<callback> (ftps_func_name, data_ref, data_len_ref, total_len, cb_data_ref);
.Ve
.Sp
The \fIftps_func_name\fR will tell what \fINet::FTPSSL\fR function requested the
callback so that your \fIcallback\fR function can determine what the data is for
and do conditional logic accordingly.  We don't provide a reference to the
\&\fINet::FTPSSL\fR object itself since the class is not recursive.  Each
\&\fINet::FTPSSL\fR object should have it's own \fIcb_dat_ref\fR to work with.  But
methods within the class can share one.
.Sp
Since we pass the data going through the data channel as a reference, you are
allowed to modify the data.  But if you do, be sure to update \fIdata_len_ref\fR
to the new data length as well if it changes.  Otherwise you will get buggy
responses.  Just be aware that if you change the length, more than likely you'll
be unable to reliably restart an upload or download via \fI\fIrestart()\fI\fR or using
\&\fI\s-1OFFSET\s0\fR in the \fIput\fR & \fIget\fR commands.
.Sp
Finally, the \fItotal_len\fR is how many bytes have already been processed.  It
does not include the data passed for the current \fIcallback\fR call.  So it will
always be zero the first time it's called.
.Sp
Once we finish processing data for the data channel, a different callback
function will be called to tell you that the data channel is closing.  That will
be your last chance to affect what is going over the data channel and to do any
needed post processing.  The end callback function must take the following
arguments:
.Sp
.Vb 1
\&   $end = B<end_callback> (ftps_func_name, total_len, cb_data_ref);
.Ve
.Sp
These arguments have the same meaning as for the callback function, except that
this function allows you to optionally provide additional data to/from the data
channel.  If reading from the data channel, it will treat the return value as
the last data returned before it was closed.  Otherwise it will be written to
the data channel before it is closed.  Please return \fIundef\fR if there is
nothing extra for the \fINet::FTPSSL\fR command to process.
.Sp
You should also take care to clean up the contents of \fIcb_data_ref\fR in the
\&\fIend_callback\fR function.  Otherwise the next callback sequence that uses this
work area may behave strangely.
.Sp
As a final note, should the data channel be empty, it is very likely that just
the \fIend_callback\fR function will be called without any calls to the \fIcallback\fR
function.
.SH "AUTHORS"
.IX Header "AUTHORS"
Marco Dalla Stella \- <kral at paranoici dot org>
.PP
Curtis Leach \- <cleach at cpan dot org> \- As of v0.05
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fINet::Cmd\fR
.PP
\&\fINet::FTP\fR
.PP
\&\fINet::SSLeay::Handle\fR
.PP
\&\fIIO::Socket::SSL\fR
.PP
\&\s-1RFC\s0 959 \- ftp://ftp.rfc\-editor.org/in\-notes/rfc959.txt <ftp://ftp.rfc-editor.org/in-notes/rfc959.txt>
.PP
\&\s-1RFC\s0 2228 \- ftp://ftp.rfc\-editor.org/in\-notes/rfc2228.txt <ftp://ftp.rfc-editor.org/in-notes/rfc2228.txt>
.PP
\&\s-1RFC\s0 2246 \- ftp://ftp.rfc\-editor.org/in\-notes/rfc2246.txt <ftp://ftp.rfc-editor.org/in-notes/rfc2246.txt>
.PP
\&\s-1RFC\s0 4217 \- ftp://ftp.rfc\-editor.org/in\-notes/rfc4217.txt <ftp://ftp.rfc-editor.org/in-notes/rfc4217.txt>
.SH "CREDITS"
.IX Header "CREDITS"
Graham Barr <gbarr at pobox dot com> \- for have written such a great
collection of modules (libnet).
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs with a \s-1FTPS\s0 log file created via options \fBDebug=>1\fR
and \fBDebugLogFile=>\*(L"file.txt\*(R"\fR along with your sample code at
http://search.cpan.org/~cleach/Net\-FTPSSL\-0.22/FTPSSL.pm <http://search.cpan.org/~cleach/Net-FTPSSL-0.22/FTPSSL.pm>.
.PP
Patches are appreciated when a log file and sample code are also provided.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2009 \- 2012 Curtis Leach. All rights reserved.
.PP
Copyright (c) 2005 Marco Dalla Stella. All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.