.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "2016-07-08" "perl v5.16.3" "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.33"
.IX Header "VERSION 0.33"

.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::FTPSSL;
\&
\&  my $ftps = Net::FTPSSL\->new(\*(Aqftp.your\-secure\-server.com\*(Aq, 
\&                              Encryption => EXP_CRYPT,
\&                              Debug => 1, DebugLogFile => "myLog.txt",
\&                              Croak => 1);
\&
\&  $ftps\->trapWarn ();     # Only call if opening a CPAN bug report.
\&
\&  $ftps\->login(\*(Aqanonymous\*(Aq, \*(Aquser@localhost\*(Aq);
\&
\&  $ftps\->cwd("/pub");
\&
\&  $ftps\->get("file");
\&
\&  $ftps\->quit();
.Ve
.PP
Since I included \fICroak => 1\fR as an option to \fInew\fR, it automatically
called \fIdie\fR for me if any \fINet::FTPSSL\fR command failed.  So there was no need
for any messy error checking in my code example!
.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\*(R"\s0 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.
TLS\s0 is the default encryption type and the more secure of the two protocols.
Set \fBuseSSL => 1\fR to use \s-1SSL.\s0
.Sp
\&\fBProxyArgs\fR \- A hash reference to pass to the proxy server.  When a proxy
server is encountered, this class uses \fINet::HTTPTunnel\fR to get through to
the server you need to talk to.  See \fINet::HTTPTunnel\fR for what values are
supported.  Options \fIremote-host\fR and \fIremote-port\fR are hard coded to the
same values as provided by \fI\s-1HOST\s0\fR and \fI\s-1PORT\s0\fR above and cannot be overridden.
.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 log file is closed when this class instance goes out of
scope.
.Sp
Instead of a file name, you may instead specify an open file handle or \s-1GLOB\s0 and
it will write the logs there insead.  (\fINot really recommended.\fR)
.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
\&\fBReuseSession\fR \- Tells the \fB\s-1FTP/S\s0\fR server that we wish to reuse the \fIcommand
channel\fR session for all \fIdata channel\fR connections.  (0/1/2/etc.)  It defaults
to \fB0\fR, no reuse.
.Sp
When requested, it will use a default \fIsession cache size\fR of \fB5\fR, but you
can increase the cache's size by setting the \fIReuseSession\fR to a larger value.
Where the \fIsession cache size\fR is (4 + the \fIReuseSession\fR value).
.Sp
\&\fBDisableContext\fR \- Tells the \fB\s-1FTP/S\s0\fR server that we don't wish to reuse the
\&\fIcommand channel\fR context for all \fIdata channel\fR connections.  (0/1)  If
option \fIReuseSession\fR or \fISSL_Client_Certificate\fR are also used, this option
is ignored!  By default the context is always reused on encrypted data channels
via \fBSSL_reuse_ctx\fR.
.Sp
\&\fBSSL_*\fR \- \s-1SSL\s0 arguments which can be applied when \fI\fIstart_SSL()\fI\fR is finally
called to encrypt the command channel.  An alternative to using
\&\fISSL_Client_Certificate\fR.  See \fIIO::Socket::SSL\fR for a list of valid
arguments.
.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-1FTP/S\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.
.Sp
See \fI\fIstart_SSL()\fI\fR in \fIIO::Socket::SSL\fR for more details on this and other
options available besides those for certificates.  If an option provided via
this hash 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 over the \fIData Channel\fR. Default value is 10240.  It does not affect
the \fICommand Channel\fR.
.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!  But if
this server also does load balancing, you are out of luck.  This option may not
be able to help you if multiple \s-1IP\s0 Addresses can be returned.
.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.
.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, PASSWORD \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.
.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 ALL\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 ALL\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 LF\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 LF\s0\fR transformation will be done.
.IP "\fImixedModeAI()\fR" 4
.IX Item "mixedModeAI()"
Mixture of \s-1ASCII &\s0 binary mode.  The server does \fI\s-1CR LF\s0\fR transfernations while
the client side does not.  (For a really weird server)
.IP "\fImixedModeIA()\fR" 4
.IX Item "mixedModeIA()"
Mixture of binary & \s-1ASCII\s0 mode.  The client does \fI\s-1CR LF\s0\fR transfernations while
the server side does not.  (For a really weird server)
.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.  (\fIThis may not be consistent across
all \s-1FTPS\s0 Servers, so don't depend on this feature without testing it first.\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 \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.  But on some servers, the remote server won't take the hint
and will always generate a unique name instead.
.Sp
If the file transfer succeeds, this function will try to 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.  If the remote server won't take the hint and we can't figure out
the name it used, we'll return a string containing a single \fB?\fR instead.  In
this case the request worked, but this command has no way to figure out what
name was generated on the remote ftps server.  And we want to return a printable
value that will evaluate to \fBtrue\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 could 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 "transfer( dest_server, \s-1REMOTE_FILE\s0 [, \s-1DEST_FILE\s0 [, \s-1OFFSET\s0]] )" 4
.IX Item "transfer( dest_server, REMOTE_FILE [, DEST_FILE [, OFFSET]] )"
Retrieves the \fI\s-1REMOTE_FILE\s0\fR from the current ftps server and uploads it to
the \fIdest_server\fR as \fI\s-1DEST_FILE\s0\fR without making any copy of the file on your
local file system.  If \fI\s-1DEST_FILE\s0\fR isn't provided, it uses \fI\s-1REMOTE_FILE\s0\fR
on the \fIdest_server\fR.
.Sp
It assumes that \fIdest_server\fR is an \fINet::FTPSSL\fR object and you have
already successfully logged onto \fIdest_server\fR and set both ends to either
binary or ascii mode!  So this function skips over the \s-1CR/LF\s0 logic and lets
the other servers handle it.  You must also set the \fICroak\fR option to the
same value on both ends.
.Sp
Finally, if logging is turned on, the logs to this function will be split
between the logs on each system.  So the logs may be a bit of a pain to follow
since you'd need to look in two places for each half.
.IP "xtransfer( dest_server, \s-1REMOTE_FILE,\s0 [\s-1DEST_FILE,\s0 [\s-1PREFIX,\s0" 4
.IX Item "xtransfer( dest_server, REMOTE_FILE, [DEST_FILE, [PREFIX,"
[\s-1POSTFIX,\s0 [\s-1BODY\s0]]]] )
.Sp
Same as \fItransfer\fR, but it uses a temporary filename on the \fIdest_server\fR
during the transfer.  And then renames it to \fI\s-1DEST_FILE\s0\fR afterwards.
.Sp
See \fIxput\fR for the meaning of the remaining parameters.
.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, NEW \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.
.Sp
Finally if the file isn't a regular file, it will return \fIundef\fR.
.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, CMD_OK, CMD_MORE, CMD_REJECT, CMD_ERROR, CMD_PROTECT\s0 and \s-1CMD_PENDING.\s0
.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 cannot 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
.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 command assumes that the \fB\s-1FTP/S\s0\fR server is configured correctly.  But
I've run into some servers where \fB\s-1HELP\s0\fR says a command is present when it's
really unknown.  So I'm assuming the reverse may be true sometimes as well.
So when you hit this issue, use \fIOverrideHELP\fR to work arround this problem.
.Sp
This method is used internally for conditional logic usually when checking
if the following \fI\s-1FTP\s0\fR commands are allowed: \fB\s-1ALLO\s0\fR, \fB\s-1NOOP\s0\fR, \fB\s-1HELP\s0\fR,
\&\fB\s-1MFMT\s0\fR, \fB\s-1MDTM\s0\fR, \fB\s-1SIZEZ\s0\fR and \fB\s-1STAT\s0\fR.  The \fB\s-1ALLO\s0\fR command is checked during
all \fIput\fR/\fIget\fR command sequences.  The other commands are not checked as
often.  The functions \fIxput\fR and \fIxtransfer\fR also tests for four more
commands: \fB\s-1STOR\s0\fR, \fB\s-1DELE\s0\fR, \fB\s-1RNFR\s0\fR and \fB\s-1RNTO\s0\fR.
.IP "all_supported( \s-1CMD1\s0 [, \s-1CMD2\s0 [, \s-1CMD3\s0 [, \s-1CMD4\s0 [, ...]]]] )" 4
.IX Item "all_supported( CMD1 [, CMD2 [, CMD3 [, CMD4 [, ...]]]] )"
Similar to \fIsupported\fR, except that it tests everything in this list of one or
more \fI\s-1FTP\s0\fR commands passed to it to see if they are supported.  If the list is
empty, or if even one command in the list isn't supported, it returns \fB\s-1FALSE\s0\fR.
Otherwise it returns \fB\s-1TRUE\s0\fR.  It will also ignore the \fBCroak\fR request.
.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, \fI\fIappend()\fI\fR and
\&\fI\fItransfer()\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, \fI\fIappend()\fI\fR and \fI\fItransfer()\fI\fR
calls.
.Sp
This \fI\s-1OFFSET\s0\fR will be automatically zeroed out after the 1st time it is used.
.IP "is_file( \s-1FILE \s0)" 4
.IX Item "is_file( FILE )"
Returns true if the passed \fIname\fR is recognized as a regular file on the remote
server.  It's assumed a regular file if the \fIsize\fR function works.
works! (\fI\s-1IE.\s0 returns a size >= 0 Bytes\fR.)
.IP "is_dir( \s-1DIRECTORY \s0)" 4
.IX Item "is_dir( DIRECTORY )"
Returns true if the passed \fIname\fR is recognized as a directory on the remote
server.  It's assumed a directory if you can \fIcwd\fR into it.
.Sp
If you don't have permission to \fIcwd\fR into that directory, this function
\&\fBwill not\fR recognize it as a directory, even if it really is one!
.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.
.IP "\fIget_log_filehandle()\fR" 4
.IX Item "get_log_filehandle()"
Returns the open file handle for the file specified by the \fBDebugLogFile\fR
option specified by \f(CW\*(C`new()\*(C'\fR.  If you did not use this option, it will return
undef.
.Sp
Just be aware that once this object goes out of scope, the returned file handle
becomes invalid.
.IP "set_dc_from_hash( \s-1HASH \s0)" 4
.IX Item "set_dc_from_hash( HASH )"
This function provides you a way to micro manage the \fI\s-1SSL\s0\fR characteristics
of the \s-1FTPS\s0 Data Channel without having to hack the Net::FTPSSL code base.
It should be called as soon as possible after the call to \fB\f(BInew()\fB\fR.
.Sp
It takes a \fI\s-1HASH\s0\fR as it's argument.  Either by value or by address.
This hash of key/value pairs will be used to control the Data Channel
\&\fI\s-1SSL\s0\fR options.
.Sp
If the key's value is set to \fIundef\fR, it is an instruction to delete an
existing Data Channel option.  If the key has a value it is an instruction to
add this key/value pair to the Data Channel options.  If the option already
exists, it will override that value.
.Sp
It returns the number of entries updated for the Data Channel.
.IP "copy_cc_to_dc( \s-1FORCE, ARRAY \s0)" 4
.IX Item "copy_cc_to_dc( FORCE, ARRAY )"
This function provides you a way to copy some of the \fI\s-1SSL\s0\fR options used
to manage the Command Channel over to the Data Channel as well without
having to hack the Net::FTPSSL code base.  It should be called as soon
as possible after the call to \fB\f(BInew()\fB\fR.
.Sp
It takes an \fI\s-1ARRAY\s0\fR as it's arguments.  Either by value or by address.
It looks up each array value in the Command Channel's \fI\s-1SSL\s0\fR characteristics
and copies them over to use as a Data Channel option.
.Sp
If the option doen't exist for the Command Channel, that array entry is ignored.
.Sp
If the option is already set in the Data Channel, the array entry overrides
the current value in the Data Channel.
.Sp
It returns the number of entries updated for the Data Channel.
.IP "\fItrapWarn()\fR" 4
.IX Item "trapWarn()"
This method is only active if \fIDebug\fR is turned on with \fIDebugLogFile\fR
provided as well.  Otherwise calling it does nothing.  This trap for \fIwarnings\fR
is automatically turned off when the the instance of this class goes out of
scope.  It returns \fB1\fR if the trap was turned on, else \fB0\fR if it wasn't.
.Sp
Calling this method causes all \fBPerl\fR \fIwarnings\fR to be written to the log
file you specified when you called \fI\fInew()\fI\fR.  The \fIwarnings\fR will appear in
the log file when they occur to assist in debugging this module.  It
automatically puts the word \fI\s-1WARNING:\s0\fR in front of the message being logged.
.Sp
So this method is only really useful if you wish to open a \fB\s-1CPAN\s0\fR ticket to
report a problem with \fINet::FTPSSL\fR and you think having the generated warning
showing up in the logs will help in getting your issue resolved.
.Sp
You may call this method for multiple \fINet::FTPSSL\fR instances and it will
cause the \fIwarning\fR to be written to multiple log files.
.Sp
If your program already traps \fIwarnings\fR before you call this method, this
code will forward the warning to your trap logic as well.
.SH "INTERPRETING THE LOGS"
.IX Header "INTERPRETING THE LOGS"
The logs generated by \fINet::FTPSSL\fR are very easy to interpret.  After you get
past the initial configuration information needed to support opening a \fI\s-1CPAN\s0\fR
ticket, it's basically the \fB\s-1FTPS\s0\fR traffic going back and forth between your
perl \fIClient\fR and the \fI\s-1FTPS\s0 Server\fR you are talking to.
.PP
Each line begins with a prefix that tells what is happening.
.PP
\&\f(CW\*(C`>>>\*(C'\fR \- Represents outbound traffic sent to the \s-1FTPS\s0 Server.
.PP
\&\f(CW\*(C`<<<\*(C'\fR \- Represents inbound traffic received from the \s-1FTPS\s0 Server.
.PP
\&\f(CW\*(C`<<+\*(C'\fR \- Represents messages from \fINet::FTPSSL\fR itself in response to
a request that doesn't hit the \fI\s-1FTPS\s0 Server\fR.
.PP
\&\f(CW\*(C`WARNING:\*(C'\fR \- Represents a trapped \fIperl warning\fR written to the logs.
.PP
\&\f(CW\*(C`SKT >>>\*(C'\fR & \f(CW\*(C`SKT <<<\*(C'\fR represent socket traffic
before the \fINet::FTPSSL\fR object gets created.
.PP
There are a couple of other rare variants to the above theme.  But they are
purely information only.  So this is basically it.
.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 959 \- \s0<http://www.rfc\-editor.org/info/rfc959>
.PP
\&\s-1RFC 2228 \- \s0<http://www.rfc\-editor.org/info/rfc2228>
.PP
\&\s-1RFC 2246 \- \s0<http://www.rfc\-editor.org/info/rfc2246>
.PP
\&\s-1RFC 4217 \- \s0<http://www.rfc\-editor.org/info/rfc4217>
.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.33/FTPSSL.pm> or
<https://metacpan.org/pod/Net::FTPSSL>.
.PP
Patches are appreciated when a log file and sample code are also provided.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2009 \- 2016 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.