Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 358 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Net::libnetFAQ.3pm b/upstream/mageia-cauldron/man3pm/Net::libnetFAQ.3pm
new file mode 100644
index 00000000..d5052ddc
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Net::libnetFAQ.3pm
@@ -0,0 +1,358 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" 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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    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 >0, 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
+.\" ========================================================================
+.\"
+.IX Title "Net::libnetFAQ 3pm"
+.TH Net::libnetFAQ 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+libnetFAQ \- libnet Frequently Asked Questions
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS "Where to get this document"
+.IX Subsection "Where to get this document"
+This document is distributed with the libnet distribution, and is also
+available on the libnet web page at
+.PP
+<https://metacpan.org/release/libnet>
+.SS "How to contribute to this document"
+.IX Subsection "How to contribute to this document"
+You may report corrections, additions, and suggestions on the
+CPAN Request Tracker at
+.PP
+<https://rt.cpan.org/Public/Bug/Report.html?Queue=libnet>
+.SH "Author and Copyright Information"
+.IX Header "Author and Copyright Information"
+Copyright (C) 1997\-1998 Graham Barr.  All rights reserved.
+This document is free; you can redistribute it and/or modify it under
+the same terms as Perl itself, i.e. under the terms of either the GNU
+General Public License or the Artistic License, as specified in the
+\&\fILICENCE\fR file.
+.PP
+Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining
+libnet as of version 1.22_02.
+.SS Disclaimer
+.IX Subsection "Disclaimer"
+This information is offered in good faith and in the hope that it may
+be of use, but is not guaranteed to be correct, up to date, or suitable
+for any particular purpose whatsoever.  The authors accept no liability
+in respect of this information or its use.
+.SH "Obtaining and installing libnet"
+.IX Header "Obtaining and installing libnet"
+.SS "What is libnet ?"
+.IX Subsection "What is libnet ?"
+libnet is a collection of perl5 modules which all related to network
+programming. The majority of the modules available provided the
+client side of popular server-client protocols that are used in
+the internet community.
+.SS "Which version of perl do I need ?"
+.IX Subsection "Which version of perl do I need ?"
+This version of libnet requires Perl 5.8.1 or higher.
+.SS "What other modules do I need ?"
+.IX Subsection "What other modules do I need ?"
+No non-core modules are required for normal use, except on os390,
+which requires Convert::EBCDIC.
+.PP
+Authen::SASL is required for AUTH support.
+.PP
+IO::Socket::SSL version 2.007 or higher is required for SSL support.
+.PP
+IO::Socket::IP version 0.25 or IO::Socket::INET6 version 2.62 is
+required for IPv6 support.
+.SS "What machines support libnet ?"
+.IX Subsection "What machines support libnet ?"
+libnet itself is an entirely perl-code distribution so it should work
+on any machine that perl runs on.
+.SS "Where can I get the latest libnet release"
+.IX Subsection "Where can I get the latest libnet release"
+The latest libnet release is always on CPAN, you will find it
+in
+.PP
+<https://metacpan.org/release/libnet>
+.SH "Using Net::FTP"
+.IX Header "Using Net::FTP"
+.SS "How do I download files from an FTP server ?"
+.IX Subsection "How do I download files from an FTP server ?"
+An example taken from an article posted to comp.lang.perl.misc
+.PP
+.Vb 1
+\&    #!/your/path/to/perl
+\&
+\&    # a module making life easier
+\&
+\&    use Net::FTP;
+\&
+\&    # for debugging: $ftp = Net::FTP\->new(\*(Aqsite\*(Aq,\*(AqDebug\*(Aq,10);
+\&    # open a connection and log in!
+\&
+\&    $ftp = Net::FTP\->new(\*(Aqtarget_site.somewhere.xxx\*(Aq);
+\&    $ftp\->login(\*(Aqusername\*(Aq,\*(Aqpassword\*(Aq);
+\&
+\&    # set transfer mode to binary
+\&
+\&    $ftp\->binary();
+\&
+\&    # change the directory on the ftp site
+\&
+\&    $ftp\->cwd(\*(Aq/some/path/to/somewhere/\*(Aq);
+\&
+\&    foreach $name (\*(Aqfile1\*(Aq, \*(Aqfile2\*(Aq, \*(Aqfile3\*(Aq) {
+\&
+\&    # get\*(Aqs arguments are in the following order:
+\&    # ftp server\*(Aqs filename
+\&    # filename to save the transfer to on the local machine
+\&    # can be simply used as get($name) if you want the same name
+\&
+\&      $ftp\->get($name,$name);
+\&    }
+\&
+\&    # ftp done!
+\&
+\&    $ftp\->quit;
+.Ve
+.SS "How do I transfer files in binary mode ?"
+.IX Subsection "How do I transfer files in binary mode ?"
+To transfer files without <LF><CR> translation Net::FTP provides
+the \f(CW\*(C`binary\*(C'\fR method
+.PP
+.Vb 1
+\&    $ftp\->binary;
+.Ve
+.SS "How can I get the size of a file on a remote FTP server ?"
+.IX Subsection "How can I get the size of a file on a remote FTP server ?"
+.SS "How can I get the modification time of a file on a remote FTP server ?"
+.IX Subsection "How can I get the modification time of a file on a remote FTP server ?"
+.SS "How can I change the permissions of a file on a remote server ?"
+.IX Subsection "How can I change the permissions of a file on a remote server ?"
+The FTP protocol does not have a command for changing the permissions
+of a file on the remote server. But some ftp servers may allow a chmod
+command to be issued via a SITE command, eg
+.PP
+.Vb 1
+\&    $ftp\->quot(\*(Aqsite chmod 0777\*(Aq,$filename);
+.Ve
+.PP
+But this is not guaranteed to work.
+.SS "Can I do a reget operation like the ftp command ?"
+.IX Subsection "Can I do a reget operation like the ftp command ?"
+.SS "How do I get a directory listing from an FTP server ?"
+.IX Subsection "How do I get a directory listing from an FTP server ?"
+.SS "Changing directory to """" does not fail ?"
+.IX Subsection "Changing directory to """" does not fail ?"
+Passing an argument of "" to \->\fBcwd()\fR has the same affect of calling \->\fBcwd()\fR
+without any arguments. Turn on Debug (\fISee below\fR) and you will see what is
+happening
+.PP
+.Vb 3
+\&    $ftp = Net::FTP\->new($host, Debug => 1);
+\&    $ftp\->login;
+\&    $ftp\->cwd("");
+.Ve
+.PP
+gives
+.PP
+.Vb 2
+\&    Net::FTP=GLOB(0x82196d8)>>> CWD /
+\&    Net::FTP=GLOB(0x82196d8)<<< 250 CWD command successful.
+.Ve
+.SS "I am behind a SOCKS firewall, but the Firewall option does not work ?"
+.IX Subsection "I am behind a SOCKS firewall, but the Firewall option does not work ?"
+The Firewall option is only for support of one type of firewall. The type
+supported is an ftp proxy.
+.PP
+To use Net::FTP, or any other module in the libnet distribution,
+through a SOCKS firewall you must create a socks-ified perl executable
+by compiling perl with the socks library.
+.SS "I am behind an FTP proxy firewall, but cannot access machines outside ?"
+.IX Subsection "I am behind an FTP proxy firewall, but cannot access machines outside ?"
+Net::FTP implements the most popular ftp proxy firewall approach. The scheme
+implemented is that where you log in to the firewall with \f(CW\*(C`user@hostname\*(C'\fR
+.PP
+I have heard of one other type of firewall which requires a login to the
+firewall with an account, then a second login with \f(CW\*(C`user@hostname\*(C'\fR. You can
+still use Net::FTP to traverse these firewalls, but a more manual approach
+must be taken, eg
+.PP
+.Vb 3
+\&    $ftp = Net::FTP\->new($firewall) or die $@;
+\&    $ftp\->login($firewall_user, $firewall_passwd) or die $ftp\->message;
+\&    $ftp\->login($ext_user . \*(Aq@\*(Aq . $ext_host, $ext_passwd) or die $ftp\->message.
+.Ve
+.SS "My ftp proxy firewall does not listen on port 21"
+.IX Subsection "My ftp proxy firewall does not listen on port 21"
+FTP servers usually listen on the same port number, port 21, as any other
+FTP server. But there is no reason why this has to be the case.
+.PP
+If you pass a port number to Net::FTP then it assumes this is the port
+number of the final destination. By default Net::FTP will always try
+to connect to the firewall on port 21.
+.PP
+Net::FTP uses IO::Socket to open the connection and IO::Socket allows
+the port number to be specified as part of the hostname. So this problem
+can be resolved by either passing a Firewall option like \f(CW"hostname:1234"\fR
+or by setting the \f(CW\*(C`ftp_firewall\*(C'\fR option in Net::Config to be a string
+in the same form.
+.SS "Is it possible to change the file permissions of a file on an FTP server ?"
+.IX Subsection "Is it possible to change the file permissions of a file on an FTP server ?"
+The answer to this is "maybe". The FTP protocol does not specify a command to change
+file permissions on a remote host. However many servers do allow you to run the
+chmod command via the \f(CW\*(C`SITE\*(C'\fR command. This can be done with
+.PP
+.Vb 1
+\&  $ftp\->site(\*(Aqchmod\*(Aq,\*(Aq0775\*(Aq,$file);
+.Ve
+.SS "I have seen scripts call a method message, but cannot find it documented ?"
+.IX Subsection "I have seen scripts call a method message, but cannot find it documented ?"
+Net::FTP, like several other packages in libnet, inherits from Net::Cmd, so
+all the methods described in Net::Cmd are also available on Net::FTP
+objects.
+.SS "Why does Net::FTP not implement mput and mget methods"
+.IX Subsection "Why does Net::FTP not implement mput and mget methods"
+The quick answer is because they are easy to implement yourself. The long
+answer is that to write these in such a way that multiple platforms are
+supported correctly would just require too much code. Below are
+some examples how you can implement these yourself.
+.PP
+sub mput {
+  my($ftp,$pattern) = \f(CW@_\fR;
+  foreach my \f(CW$file\fR (glob($pattern)) {
+    \f(CW$ftp\fR\->put($file) or warn \f(CW$ftp\fR\->message;
+  }
+}
+.PP
+sub mget {
+  my($ftp,$pattern) = \f(CW@_\fR;
+  foreach my \f(CW$file\fR ($ftp\->ls($pattern)) {
+    \f(CW$ftp\fR\->get($file) or warn \f(CW$ftp\fR\->message;
+  }
+}
+.SH "Using Net::SMTP"
+.IX Header "Using Net::SMTP"
+.SS "Why can't the part of an Email address after the @ be used as the hostname ?"
+.IX Subsection "Why can't the part of an Email address after the @ be used as the hostname ?"
+The part of an Email address which follows the @ is not necessarily a hostname,
+it is a mail domain. To find the name of a host to connect for a mail domain
+you need to do a DNS MX lookup
+.SS "Why does Net::SMTP not do DNS MX lookups ?"
+.IX Subsection "Why does Net::SMTP not do DNS MX lookups ?"
+Net::SMTP implements the SMTP protocol. The DNS MX lookup is not part
+of this protocol.
+.SS "The verify method always returns true ?"
+.IX Subsection "The verify method always returns true ?"
+Well it may seem that way, but it does not. The verify method returns true
+if the command succeeded. If you pass verify an address which the
+server would normally have to forward to another machine, the command
+will succeed with something like
+.PP
+.Vb 1
+\&    252 Couldn\*(Aqt verify <someone@there> but will attempt delivery anyway
+.Ve
+.PP
+This command will fail only if you pass it an address in a domain
+the server directly delivers for, and that address does not exist.
+.SH "Debugging scripts"
+.IX Header "Debugging scripts"
+.SS "How can I debug my scripts that use Net::* modules ?"
+.IX Subsection "How can I debug my scripts that use Net::* modules ?"
+Most of the libnet client classes allow options to be passed to the
+constructor, in most cases one option is called \f(CW\*(C`Debug\*(C'\fR. Passing
+this option with a non-zero value will turn on a protocol trace, which
+will be sent to STDERR. This trace can be useful to see what commands
+are being sent to the remote server and what responses are being
+received back.
+.PP
+.Vb 1
+\&    #!/your/path/to/perl
+\&
+\&    use Net::FTP;
+\&
+\&    my $ftp = new Net::FTP($host, Debug => 1);
+\&    $ftp\->login(\*(Aqgbarr\*(Aq,\*(Aqpassword\*(Aq);
+\&    $ftp\->quit;
+.Ve
+.PP
+this script would output something like
+.PP
+.Vb 6
+\& Net::FTP: Net::FTP(2.22)
+\& Net::FTP:   Exporter
+\& Net::FTP:   Net::Cmd(2.0801)
+\& Net::FTP:   IO::Socket::INET
+\& Net::FTP:     IO::Socket(1.1603)
+\& Net::FTP:       IO::Handle(1.1504)
+\&
+\& Net::FTP=GLOB(0x8152974)<<< 220 imagine FTP server (Version wu\-2.4(5) Tue Jul 29 11:17:18 CDT 1997) ready.
+\& Net::FTP=GLOB(0x8152974)>>> user gbarr
+\& Net::FTP=GLOB(0x8152974)<<< 331 Password required for gbarr.
+\& Net::FTP=GLOB(0x8152974)>>> PASS ....
+\& Net::FTP=GLOB(0x8152974)<<< 230 User gbarr logged in.  Access restrictions apply.
+\& Net::FTP=GLOB(0x8152974)>>> QUIT
+\& Net::FTP=GLOB(0x8152974)<<< 221 Goodbye.
+.Ve
+.PP
+The first few lines tell you the modules that Net::FTP uses and their versions,
+this is useful data to me when a user reports a bug. The last seven lines
+show the communication with the server. Each line has three parts. The first
+part is the object itself, this is useful for separating the output
+if you are using multiple objects. The second part is either \f(CW\*(C`<<<<\*(C'\fR to
+show data coming from the server or \f(CW\*(C`&gt&gt&gt&gt\*(C'\fR to show data
+going to the server. The remainder of the line is the command
+being sent or response being received.
+.SH "AUTHOR AND COPYRIGHT"
+.IX Header "AUTHOR AND COPYRIGHT"
+Copyright (C) 1997\-1998 Graham Barr.  All rights reserved.