diff options
Diffstat (limited to 'upstream/debian-unstable/man3/Net::libnetFAQ.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/Net::libnetFAQ.3perl | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/Net::libnetFAQ.3perl b/upstream/debian-unstable/man3/Net::libnetFAQ.3perl new file mode 100644 index 00000000..e5f8553d --- /dev/null +++ b/upstream/debian-unstable/man3/Net::libnetFAQ.3perl @@ -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 3perl" +.TH Net::libnetFAQ 3perl 2024-01-12 "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`>>>>\*(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. |