CONTENUTI

  • NOME
  • SINOSSI
  • DESCRIZIONE
  • SOPRAVVISSUTO
  • COSTRUTTORE
  • METODI
    • Metodi per gli avventurosi
  • LA CLASSE DEI DATI
  • UNIMPEGNATO
  • SEGNALAZIONE DI BUG
  • AUTORE
  • VEDI ANCHE
  • ESEMPI DI UTILIZZO
  • CREDITI
  • DIRITTO D'AUTORE
  • LICENZA

NOME

Net::FTP - Classe client FTP

SINOSSI

use Net::FTP;$ftp= Net::FTP->new("some.host.name", Debug =>0)ordie"Cannot connect to some.host.name: [email protected]";$ftp->login("anonymous",'[email protected]')ordie"Cannot login ",$ftp->message;$ftp->cwd("/pub")ordie"Cannot change working directory ",$ftp->message;$ftp->get("that.file")ordie"get failed ",$ftp->message;$ftp->quit;

DESCRIZIONE

Net::FTP è una classe che implementa un semplice client FTP in Perl, come descritto in RFC959. Fornisce wrapper per il sottoinsieme dei comandi RFC959 comunemente utilizzati. Se è installato IO::Socket::IP o IO::Socket::INET6, fornisce anche il supporto per IPv6 come definito in RFC2428. E con IO::Socket::SSL installato, fornisce il supporto per FTPS implicito e FTPS esplicito, come definito in RFC4217.

La classe Net::FTP è una sottoclasse di Net::Cmd e (a seconda della disponibilità) di IO::Socket::IP, IO::Socket::INET6 o IO::Socket::INET.

SOPRAVVISSUTO

FTP è l'acronimo di File Transfer Protocol. È un modo per trasferire file tra macchine collegate in rete. Il protocollo definisce un client (i cui comandi sono forniti da questo modulo) e un server (non implementato in questo modulo). La comunicazione viene sempre avviata dal client e il server risponde con un messaggio e un codice di stato (e talvolta con dei dati).

Il protocollo FTP consente di inviare o prelevare file dal server. Ogni trasferimento comporta un file locale (sul client) e un file remoto (sul server). In questo modulo, lo stesso nome di file verrà utilizzato sia per il locale che per il remoto, se ne viene specificato solo uno. Ciò significa che il trasferimento del file remoto /path/to/file cercherà di inserire il file in /path/to/file locale, a meno che non si specifichi un nome di file locale.

Il protocollo definisce anche diversi standard traduzioni che il file può subire durante il trasferimento. Si tratta di ASCII, EBCDIC, binario e byte. ASCII è il tipo predefinito e indica che il mittente dei file tradurrà le estremità delle righe in una rappresentazione standard che il destinatario tradurrà poi nella propria rappresentazione locale. EBCDIC indica che il file trasferito è in formato EBCDIC. Il formato binario (noto anche come immagine) invia i dati come flusso contiguo di bit. Il formato Byte trasferisce i dati come byte, i cui valori rimangono invariati a prescindere dalle differenze di dimensione dei byte tra le due macchine (in teoria, in pratica si dovrebbe usare solo se si sa veramente cosa si sta facendo). Questa classe non supporta i formati EBCDIC o byte e, se si tenta di utilizzarli, si imposta il formato binario.

COSTRUTTORE

nuovo ([ HOST ] [, OPTIONS ])

È il costruttore di un nuovo oggetto Net::FTP. HOST è il nome dell'host remoto a cui è richiesta una connessione FTP.

HOST è opzionale. Se HOST non è indicato, può essere passato come il parametro Host descritta di seguito.

OPTIONS vengono passati in modo simile a un hash, utilizzando coppie di chiavi e valori. Le opzioni possibili sono:

Ospite - Host FTP a cui connettersi. Può essere un singolo scalare, come definito per l'opzione PeerAddr in IO::Socket::INET, oppure un riferimento a un array di host da provare a turno. Il metodo "host" restituirà il valore utilizzato per la connessione all'host.

Firewall - Il nome di una macchina che funge da firewall FTP. Può essere sovrascritto da una variabile d'ambiente FTP_FIREWALL. Se viene specificato e l'host indicato non può essere collegato direttamente, la connessione viene effettuata alla macchina firewall e la stringa @hostname viene aggiunta all'identificativo di accesso. Questo tipo di configurazione viene anche chiamata proxy ftp.

Tipo di firewall - Il tipo di firewall in esecuzione sulla macchina indicata da Firewall. Questo può essere sovrascritto da una variabile d'ambiente FTP_FIREWALL_TYPE. Per un elenco dei tipi consentiti, vedere la descrizione di ftp_firewall_type in Net::Config.

Dimensione del blocco - È la dimensione del blocco che Net::FTP utilizzerà durante i trasferimenti. (valore predefinito: 10240)

Porta - Il numero di porta a cui connettersi sul computer remoto per la connessione FTP.

SSL - Se la connessione deve essere effettuata fin dall'inizio con SSL, contrariamente all'aggiornamento successivo con starttls.

SSL_* - Argomenti SSL che verranno applicati quando si aggiorna la connessione di controllo o di dati a SSL. È possibile utilizzare gli argomenti SSL come documentato in IO::Socket::SSL, ma di solito utilizza già gli argomenti giusti.

Timeout - Imposta un valore di timeout in secondi (predefinito a 120).

Debug - livello di debug (vedere il metodo debug in Net::Cmd)

Passivo - Se impostato su un valore diverso da zero, tutti i trasferimenti di dati saranno effettuati in modalità passiva. Se è impostato su zero, i trasferimenti di dati avverranno in modalità attiva. Se la macchina è connessa direttamente a Internet, sia la modalità passiva che quella attiva dovrebbero funzionare ugualmente bene. Dietro la maggior parte delle configurazioni di firewall e NAT, la modalità passiva ha maggiori possibilità di funzionare. Tuttavia, in alcune rare configurazioni di firewall, la modalità attiva funziona quando quella passiva non funziona. Alcuni server FTP molto vecchi potrebbero non implementare i trasferimenti passivi. Se non viene specificata, la modalità di trasferimento viene impostata dalla variabile d'ambiente FTP_PASSIVE o, se questa non è impostata, dalle impostazioni effettuate dal parametro libnetcfg . Se nessuno di questi casi è applicabile, viene utilizzata la modalità passiva.

Hash - Se viene dato un riferimento a un handle di file (ad esempio, *STDERR), stampa i segni di hash (#) su quel filehandle ogni 1024 byte. Questo richiama semplicemente il metodo hash() in modo che i segni di hash vengano visualizzati per tutti i trasferimenti. Naturalmente, è possibile chiamare il metodo hash() esplicitamente ogni volta che lo si desidera.

Indirizzo locale - Indirizzo locale da utilizzare per tutte le connessioni socket. Questo argomento sarà passato alla superclasse, cioè IO::Socket::INET o IO::Socket::IP.

Dominio - Dominio da utilizzare, ad esempio AF_INET o AF_INET6. Questo argomento sarà passato alla superclasse IO::Socket. Può essere usato per imporre IPv4 anche con IO::Socket::IP, che sarebbe predefinito su IPv6. Famiglia è accettato come nome alternativo per Dominio.

Se il costruttore fallisce, verrà restituito undef e verrà visualizzato un messaggio di errore in [email protected]

METODI

Se non diversamente indicato, tutti i metodi restituiscono un valore vero o falso con il valore vero significa che l'operazione ha avuto successo. Quando un metodo dichiara di restituire un valore, il fallimento sarà restituito come undef o un elenco vuoto.

Net::FTP eredita da Net::Cmd quindi i metodi definiti in Net::Cmd possono essere usati per inviare comandi al server FTP remoto, oltre ai metodi qui documentati.

login ([LOGIN [,PASSWORD [, ACCOUNT] ] ])

Accede al server FTP remoto con le informazioni di login fornite. Se non vengono forniti argomenti, l'opzione Net::FTP utilizza il metodo Net::Netrc per cercare le informazioni di accesso all'host collegato. Se non vengono trovate informazioni, il login di anonimo viene utilizzato. Se non viene fornita alcuna password e il login è anonimo allora [email protected] sarà usato per la password.

Se la connessione avviene tramite un firewall, il parametro authorize sarà richiamato senza argomenti.

starttls ()

Aggiorna la connessione semplice esistente in SSL. Gli argomenti SSL devono essere forniti in new perché sono necessari anche per le connessioni dati.

stoptls ()

Riduce la connessione SSL esistente a semplice. Questo è necessario per lavorare con alcuni helper FTP nei firewall, che devono vedere i comandi PORT e PASV e le risposte per aprire dinamicamente le porte necessarie. In questo caso starttls viene solitamente utilizzato solo per proteggere l'autorizzazione.

prot ( LEVEL )

Imposta il tipo di protezione del canale dati che il client e il server utilizzeranno. Solo LEVELC (clear) e P (private) sono supportati.

host ()

Restituisce il valore utilizzato dal costruttore e passato alla superclasse IO::Socket per connettersi all'host.

conto( ACCT )

Imposta una stringa che identifica l'account dell'utente.

autorizzare ( [AUTH [, RESP]])

È un protocollo utilizzato da alcuni proxy ftp del firewall. Viene utilizzato per autorizzare l'utente a inviare dati. Se entrambi gli argomenti non sono specificati, allora authorize utilizza Net::Netrc per effettuare una ricerca.

sito (ARGS)

Invia un comando SITE al server remoto e attende una risposta.

Restituisce la cifra più significativa del codice di risposta.

ascii ()

Trasferisce il file in ASCII. Se necessario, verrà eseguita la traduzione CRLF

binario ()

Trasferisce il file in modalità binaria. Non verrà eseguita alcuna trasformazione.

Suggerimento: Se sia il server che il client utilizzano la stessa terminazione di riga per i file di testo, sarà più veloce trasferire tutti i file in modalità binaria.

tipo ( [ TYPE ] )

Imposta o ottiene se i file saranno trasferiti in modalità ASCII o binaria.

rinominare ( OLDNAME, NEWNAME )

Rinomina un file sul server FTP remoto da OLDNAME a NEWNAME. Ciò avviene inviando i comandi RNFR e RNTO.

eliminare ( FILENAME )

Invia una richiesta al server per cancellare FILENAME.

cwd ( [ DIR ] )

Tentativo di cambiare la directory con quella indicata in $dir. Se $dir è "..", l'FTP CDUP viene utilizzato per tentare di spostarsi verso l'alto di una directory. Se non viene fornita alcuna directory, si tenta di cambiare la directory nella directory principale.

cdup ()

Cambia la directory al genitore della directory corrente.

passivo ( [ PASSIVE ] )

Imposta o ottiene se le connessioni dati saranno avviate in modalità passiva.

pwd ()

Restituisce il percorso completo della directory corrente.

riavvio ( WHERE )

Imposta l'offset di byte da cui iniziare il prossimo trasferimento di dati. Net::FTP registra semplicemente questo valore e lo utilizza durante il successivo trasferimento di dati. Per questo motivo questo metodo non restituisce un errore, ma la sua impostazione può causare il fallimento di un successivo trasferimento di dati.

rmdir ( DIR [, RECURSE ])

Rimuove la directory con il nome DIR. Se RECURSE è vero allora rmdir tenterà di cancellare tutto ciò che si trova all'interno della directory.

mkdir ( DIR [, RECURSE ])

Crea una nuova directory con il nome DIR. Se RECURSE è vero allora mkdir tenterà di creare tutte le directory nel percorso indicato.

Restituisce il percorso completo della nuova directory.

alloc ( SIZE [, RECORD_SIZE] )

Il comando alloc consente di fornire al server ftp un suggerimento sulla dimensione del file che sta per essere trasferito utilizzando il comando ALLO ftp. Alcuni sistemi di memorizzazione lo utilizzano per prendere decisioni intelligenti su come memorizzare il file. Il comando SIZE rappresenta la dimensione del file in byte. L'argomento RECORD_SIZE indica la dimensione massima del record o della pagina per i file inviati con una struttura di record o di pagina.

La dimensione del file viene determinata e inviata al server automaticamente per i file normali, per cui questo metodo deve essere richiamato solo se si stanno trasferendo dati da un socket, da una named pipe o da un altro flusso non associato a un file normale.

ls ( [ DIR ] )

Ottiene un elenco di directory di DIRo della directory corrente.

In un contesto di array, restituisce un elenco di righe restituite dal server. In un contesto scalare, restituisce un riferimento a un elenco.

dir ( [ DIR ] )

Ottiene un elenco di directory di DIRo della directory corrente in formato lungo.

In un contesto di array, restituisce un elenco di righe restituite dal server. In un contesto scalare, restituisce un riferimento a un elenco.

get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] )

Ottenere REMOTE_FILE dal server e memorizzarlo localmente. LOCAL_FILE può essere un nome di file o un filehandle. Se non viene specificato, il file verrà memorizzato nella directory corrente con lo stesso nome di foglia del file remoto.

Se WHERE viene dato, allora il primo file WHERE del file non verranno trasferiti e i byte rimanenti verranno aggiunti al file locale, se già esistente.

Restituisce LOCAL_FILEo il nome del file locale generato se LOCAL_FILE non viene fornito. Se viene riscontrato un errore, viene restituito undef.

put ( LOCAL_FILE [, REMOTE_FILE ] )

Mette un file sul server remoto. LOCAL_FILE può essere un nome o un filehandle. Se LOCAL_FILE è un filehandle, allora REMOTE_FILE deve essere specificato. Se REMOTE_FILE non viene specificato, il file verrà memorizzato nella directory corrente con lo stesso nome di foglia di LOCAL_FILE.

Restituisce REMOTE_FILEo il nome del file remoto generato se REMOTE_FILE non viene fornito.

NOTA: Se per qualche motivo il trasferimento non viene completato e viene restituito un errore, i contenuti trasferiti non verranno rimossi automaticamente.

put_unique ( LOCAL_FILE [, REMOTE_FILE ] )

Come put, ma utilizza l'opzione STOU .

Restituisce il nome del file sul server.

append ( LOCAL_FILE [, REMOTE_FILE ] )

Come put, ma aggiunge al file sul server remoto.

Restituisce REMOTE_FILEo il nome del file remoto generato se REMOTE_FILE non viene fornito.

nome_unico ()

Restituisce il nome dell'ultimo file memorizzato sul server utilizzando l'opzione STOU .

mdtm ( FILE )

Restituisce il comando tempo di modifica del file dato

dimensione ( FILE )

Restituisce la dimensione in byte del file dato, memorizzata sul server remoto.

NOTA: La dimensione riportata è quella del file memorizzato sul server remoto. Se il file viene successivamente trasferito dal server in modalità ASCII e il server remoto e il computer locale hanno idee diverse su "End Of Line", la dimensione del file sul computer locale dopo il trasferimento può essere diversa.

supportato ( CMD )

Restituisce TRUE se il server remoto supporta il comando dato.

hash ( [FILEHANDLE_GLOB_REF],[ BYTES_PER_HASH_MARK] )

Chiamato senza parametri o con il primo argomento falso, i segni di hash vengono soppressi. Se il primo argomento è vero ma non è un riferimento a un glob di handle di file, viene utilizzato *STDERR. Il secondo argomento è il numero di byte per ogni segno di hash stampato, per impostazione predefinita 1024. In tutti i casi il valore di ritorno è un riferimento a un array di due elementi: il riferimento al glob del filehandle e i byte per marcatura hash.

caratteristica ( NOME )

Determina se il server supporta la caratteristica specificata. Il valore restituito è un elenco di righe con cui il server ha risposto per descrivere le opzioni supportate per la caratteristica indicata. Se la funzione non è supportata, viene restituito un elenco vuoto.

if($ftp->feature('MDTM')){# Do something}if(grep {/bTLSb/}$ftp->feature('AUTH')){# Server supports TLS}

I metodi seguenti possono restituire risultati diversi a seconda di come vengono chiamati. Se l'utente chiama esplicitamente uno dei metodi pasv o port questi metodi restituiranno un risultato vero o falso valore. Se l'utente non chiama nessuno di questi metodi, il risultato sarà un riferimento a un oggetto Net::FTP::dataconn basato su un oggetto.

nlst ( [ DIR ] )

Invia un NLST al server, con un parametro opzionale.

elenco ( [ DIR ] )

Come nlst ma utilizzando l'opzione LIST comando

retr ( FILE )

Inizia il recupero di un file chiamato FILE dal server remoto.

stor ( FILE )

Indica al server che si desidera memorizzare un file. FILE è il nome del nuovo file che deve essere creato.

stou ( FILE )

Come stor ma utilizzando l'opzione STOU il nome del file unico che è stato creato sul server sarà disponibile tramite il comando STOU. Il nome del file unico creato sul server sarà disponibile tramite il comando unique_name dopo la chiusura della connessione dati.

appe ( FILE )

Indica al server che si desidera aggiungere alcuni dati alla fine di un file chiamato FILE. Se questo file non esiste, crearlo.

Se per qualche motivo si vuole avere il controllo completo sulla connessione dei dati, questo include la generazione e la chiamata al metodo response quando necessario, l'utente può utilizzare questi metodi.

Tuttavia, la chiamata di questi metodi influisce solo sull'uso dei metodi precedenti che possono restituire una connessione dati. Non hanno alcun effetto sui metodi get, put, put_unique e quelli che non richiedono connessioni dati.

porta ( [ PORT ] )
eprt ( [ PORT ] )

Invia un PORT (IPv4) o EPRT (IPv6) al server. Se PORT è specificato, viene inviato al server. In caso contrario, viene creato un socket di ascolto e le informazioni corrette vengono inviate al server.

pasv ()
epsv ()

Indica al server di passare in modalità passiva (pasv per IPv4, epsv per IPv6). Restituisce il testo che rappresenta la porta su cui il server è in ascolto; questo testo è in una forma adatta per essere inviato a un altro server ftp utilizzando il comando port o eprt ...o eprt.

I seguenti metodi possono essere utilizzati per trasferire file tra due server remoti, a condizione che questi due server possano connettersi direttamente tra loro.

pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )

Questo metodo esegue un trasferimento di file tra due server ftp remoti. Se DEST_FILE è omesso, il nome della foglia di SRC_FILE verrà utilizzato.

pasv_xfer_unique ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )

Come pasv_xfer ma il file viene memorizzato sul server remoto utilizzando il comando STOU.

pasv_wait ( NON_PASV_SERVER )

Questo metodo può essere utilizzato per attendere il completamento di un trasferimento tra un server passivo e un server non passivo. Il metodo deve essere chiamato sul server passivo con l'opzione Net::FTP del server non passivo passato come argomento.

abort ()

Interrompe il trasferimento di dati in corso.

quit ()

Invia il comando QUIT al server FTP remoto e chiude la connessione socket.

Metodi per i più avventurosi

quot (CMD [,ARGS])

Invia un comando, che Net::FTP non supporta direttamente, al server remoto e attende una risposta.

Restituisce la cifra più significativa del codice di risposta.

ATTENZIONE Questa chiamata deve essere utilizzata solo per i comandi che non richiedono connessioni dati. Un uso improprio di questo metodo può bloccare la connessione.

can_inet6 ()

Restituisce se è possibile utilizzare IPv6.

can_ssl ()

Restituisce se è possibile utilizzare SSL.

LA CLASSE dataconn

Alcuni dei metodi definiti in Net::FTP restituiscono un oggetto che sarà derivato dalla classe Net::FTP::dataconn . Vedere Net::FTP::dataconn per maggiori dettagli.

UNIMPLEMENTATO

I seguenti comandi RFC959 non sono stati implementati:

SMNT

Monta una struttura di file system diversa senza modificare le informazioni di login o di accounting.

AIUTO

Chiede al server "informazioni utili" (così dice l'RFC) sui comandi accettati.

MODO

Specifica la modalità di trasferimento (flusso, blocco o compresso) per il file da trasferire.

SYST

Richiede l'identificazione del sistema del server remoto.

STAT

Richiesta dello stato del server remoto.

STRU

Specifica la struttura del file da trasferire.

REIN

Reinizializza la connessione, eliminando tutte le informazioni di I/O e di account.

SEGNALAZIONE DI BUG

Quando si segnalano bug/problemi, si prega di includere il maggior numero di informazioni possibile. Potrebbe essere difficile per me riprodurre il problema poiché quasi ogni configurazione è diversa.

Un piccolo script che riproduca il problema sarà probabilmente d'aiuto. Sarebbe anche utile se questo script fosse eseguito con le opzioni extra Debug => 1 passate al costruttore e l'output fosse inviato con la segnalazione del bug. Se non è possibile includere un piccolo script, si prega di includere una traccia di debug di un'esecuzione del programma che presenta il problema.

AUTORE

Graham Barr [email protected].

Steve Hay [email protected] sta mantenendo libnet a partire dalla versione 1.22_02.

VEDERE ANCHE

Net::Netrc, Net::Cmd, IO::Socket::SSL

ftp(1), ftpd(8), RFC 959, RFC 2428, RFC 4217 http://www.ietf.org/rfc/rfc959.txt http://www.ietf.org/rfc/rfc2428.txt http://www.ietf.org/rfc/rfc4217.txt

UTILIZZARE GLI ESEMPI

Per un esempio di utilizzo di Net::FTP vedere

http://www.csh.rit.edu/~adam/Progs/

autoftp è un programma che può recuperare, inviare o elencare file tramite il protocollo FTP in modo non interattivo.

CREDITI

Henry Gabryjelski <[email protected]> - per il suggerimento di creare le directory in modo ricorsivo.

Nathan Torkington <[email protected]> - per alcuni suggerimenti sulla documentazione.

Roderick Schertler <[email protected]> - per vari input

COPYRIGHT

Copyright (C) 1995-2004 Graham Barr. Tutti i diritti riservati.

Copyright (C) 2013-2017 Steve Hay. Tutti i diritti riservati.

LICENZA

Questo modulo è un software gratuitoe; è possibile ridistribuirlo e/o modificarlo secondo gli stessi termini del Perl stesso, cioè secondo i termini della GNU General Public License o della Artistic License, come specificato nel file LICENZA del file.