___ ___   _   ___  __  __ ___
| _ \ __| /_\ |   \|  \/  | __|	    ftplib.ksh - A Korn Shell FTP Library
|   / _| / _ \| |) | |\/| | _|	     Heiner Steven (heiner.steven@odn.de)
|_|_\___/_/ \_\___/|_|  |_|___|

@(#) README 1.5 00/07/15


INTRODUCTION

This is a fragment of a Korn Shell function library, an interface
to commands of the File Transfer Protocol (FTP) as described
in RFC 959. It should give an user easy to use functions,
and finer error control than a mere automation of an "ftp"
client would have given.


STATUS OF THIS LIBRARY

The library is only a case study, it is by no means a stable,
useable product! Use it at your own risk. Only a very basic
set of FTP commands is implemented:

	ftp_open host [port]
	ftp_close
	ftp_login [user [pasword [account]]]
	ftp_quit
	ftp_dir
	ftp_get remotefile [localfile]
	ftp_put localfile [remmotefile]
	ftp_cd directory
	ftp_pwd
	ftp_passive
	ftp_binary
	ftp_ascii
	ftp_debug

A small test program "ftpget" is part of the distribution:

	ftpget host:/pub/ls-lR

It automatically gets the remote files specified on the command
line to the local system using FTP. A remote file may be
specified in a syntax similar to the one used by "rcp":

	[user[:password]@]host:[path]

Usage message:

	ftpget - get file(s) using FTP, 1.5 (hs '00)
	usage: ftpget [-r] [-P] [-d debug] [user[:passwd]@]host:[path]
	  -r:  recurse into subdirectories (not working yet)
	  -P:  use "passive mode" for data transfer
	  -d:  set debug level (0-4)


REQUIREMENTS

The library needs two external programs for TCP connections:

    telnet	(which is fairly standard), 

and

    netcat (or "nc")

which used to be available directly from the author (hobbit@avian.org):

    http://199.103.168.8/web1/hak/netcat.html

Otherwise you may get it from one of the following sites:

ftp://metalab.unc.edu/pub/linux/distributions/trinux/tools/nc110.tgz
ftp://ftp.uni-stuttgart.de/pub/org/uni-s/rus/security/unix/hobbit/nc110.tgz
ftp://ftp.rge.com/pub/security/coast/mirrors/avian.org/netcat/nc110.tgz

Some systems (i.e. some Linux distributions) already have the
command installed, sometimes it is called "nc". You may want
to check this before downloading the source files and compiling
them on your own ;-)


INTERNALS

The library implements a subset of the FTP protocol as described
in RFC 595 (http://www.ietf.org/rfc/rfc0959.txt).

It does not need a "ftp" co-process, but establishes TCP
connections on it's own to handle the FTP protocol.

ftp_open starts a "telnet" process as a Korn Shell co-process,
and uses this for a control connection to the server to issue FTP
commands (the RFC calls this the "client protocol interpreter").

Some commands (i.e. "ftp_dir", "ftp_get", "ftp_put") require
a second TCP data connection (handled by a "client data
transfer process", DTP). This connection is established using
"netcat". Normally the FTP server initiates data connections
to the client, and the DTP already has to listen on local
port. This cannot be implemented using "telnet".


PORTABILITY

At this time the library only works with Korn Shells (ksh88). It
does not work with the Bourne shell, because it uses co-processes
and many ksh-specific ideoms. It does not work with the new Korn
Shell (ksh93, or dtksh), because of the usage of local variables.

Porting to ksh93 should be easy. If ksh93 is more widely used,
I maybe will rewrite the library to take advantage of some
ksh93 features, in particular namerefs.


AUTHOR

The library was written by Heiner Steven (heiner.steven@odn.de), and
it's home page is at Heiner's SHELLdorado:

	http://shelldorado.com/

If you have comments or suggestions regarding this library,
I would be happy to hear from you: heiner.steven@odn.de