
                       What is FTP? How does it work?

                     Copright (c) 1995, by Ian Mapleson.

                          Last Revision: 1/Mar/95


(NB: all example commands and ftp program output have been indented by two
spaces in order to deliniate this data from the surrounding text)

(NB#2: if you are already familiar with using ftp to download files, but want
to know how to _upload_ files, then goto Part 2)


                   ---------------< Part 1 >---------------

             Introduction & how to download files from an ftp site

'ftp' stands for File Transfer Protocol. It is a means by which one 
may transfer files to and from remote sites, a site being any computer
system in the world that is accessible on the Internet and has an ftp server
set up for it.

Ftp sites contain vast amounts of data on EVERY subject imaginable. There
are hundreds of thousands of sites world wide.

Some of them contain files for Doom related stuff. :)

There is a single central site for Doom information and it is called
ftp.cdrom.com which is in the USA.

Other sites around the world 'mirror' tp.orst.edu. This means that they,
every night (sometimes less often) update their files so that they contain
exactly the same files as ftp.cdrom.com in their Doom directory. Thus, if
someone far away has slow access to ftp.cdrom.com, they can use a mirror site
instead which will have better data transfer rates.

Every site has a name, but the name is really just an alias for a code
number, called an IP address. This number is given in square brackets in
the list I sent for each site. Some ftp programs are not able to translate
the names to numbers and so one needs the actual IP addresses.

What I would say next depends on what kind of ftp program you're using. Some
are command line based, like the ftp command on Unix. Others are graphical
and might run under something like Windows. So, here is some general info
and examples.


The vast majority of sites world wide are not freely accessible, ie. the 
only people who can access them are people who have user accounts at that
site. The University here (Heriot Watt in Edinburgh, Scotland) is such an
example.

But there are also a LARGE number of sites (probably around 300000+) for
which ANYONE can login to them and retrieve (and in some cases send) files.
These are called 'anonymous' ftp sites because it doesn't matter who you
are, you can use them.

To access an anonymous ftp site, one ftp's (pronounced 'Eff Tee Peez') to
the appropriate site, perhaps via a command like:

  ftp flinux.tu-graz.ac.at

and then, assuming the machine is successful in accessing the site, one is
presented with a login page. This is what I get for this site, which is
based in Austria, Europe (the machine I am using is called 'brahma', by the
way):

  brahma% ftp flinux.tu-graz.ac.at
  Connected to flinux.tu-graz.ac.at.
  220 flinux FTP server (Linux flinux 1.1.67 #1 Tue Nov 29 12:50:51 GMT-0100 1994 i386) ready.
  Name (flinux.tu-graz.ac.at:mapleson):


Most sites will have something like this when you access them. Now, since
one wants to login as an anonymous user, one enters the word 'anonymous' as
one's name. On this site, you get this:


 Name (flinux.tu-graz.ac.at:mapleson): anonymous
 331 Guest login ok, send e-mail address as password.
 Password:


At this stage, the site wants you to enter your full email address as a
password. This enables the site manager to assess the load that is being put
on their server and so ease administration.

So, I enter:

  mapleson@cee.hw.ac.uk

You would enter your email address instead. Note that when entering your email
address the ftp host will not echo what you type, so type carefully.

When I enter my address, it says:


  230-
  230-   All transfers are logged with your host name and email address.
  230-   If you don't like this policy, disconnect now!
  230-
  230-Welcome, archive user from brahma.cee.hw.ac.uk.
  230-This is an experimental FTP server. If have any unusual problems,
  230-please report them via e-mail to ftpadmin@flinux.tu-graz.ac.at .
  230-If you do have problems, please try using a dash (-) as the first character
  230-of your password -- this will turn off the continuation messages that may
  230-be confusing your ftp client.
  230-
  230-Local Time is Tue Dec  6 19:23:35 1994.
  230-
  230-You are user 3 out of a maximum 20.
  230-
  230-
  230-----------------------------------------------------------------------
  230-
  230-README           ... some information to this archive
  230-incoming         ... if you want to upload -> do it in this directory
  230-pub              ... the archive ...
  230-
  230-
  230 Guest login ok, access restrictions apply.
  ftp> 


This is a typical 'welcome' page for an ftp site.

What the site actually is is just one big directory structure of files that
one may browse through using the usual 'cd' and 'dir' commands. When you
see a file you want, you can get it using the 'get' command. You can see the
details of just one particular file, or group of files, by being more specific
with the 'dir' command, eg. entering 'dir filename.zip' will display the
directory information for just that file. This is an easy way to see if a
particular file is actually present in a directory without having to list the
entire directory (of course, this relies on you knowing the exact spelling
of the file name. Usually, the presence of capital letters in a file name
_does_ make a difference).

Transferring a file _from_ the ftp site _to_ your site is called 'downloading',
whilst sending a file from your site to the ftp site is called 'uploading'.

Some directories on ftp sites are not accessible as these may be administrative
directories which anonymous users should have no interest in.

Most sites have a 'pub' directory and this is where the files of interest
to anyone usually are. However, this is not always the case. Most sites have
some kind of 'README' file which explains where everything is. There is often
a complete recursive file listing of the ftp site, sometimes called 'FILELIST',
but often called 'ls-lR' or something similar. You can download this to see
a complete list of _everything_ on the ftp site, but beware as this file is
often very large! :)

Most files are not just plain ASCII text; such files may be image files
(like GIF or JPG, etc) or programs, tar files, zip files, a whole variety
of compression formats used to save space. These have to be downloaded in
'binary' mode, so one enters 'bin' or perhaps 'image' to switch to binary
mode.

(quick info: ASCII characters are 7 bits with the 8th bit always set to
zero. A binary file will be mostly data of 8 bits in size, such as an
executable program. Hence, in order to download/upload binary files, you
have to tell the ftp program that you want to deal with binary, and not ASCII,
data).

In general, it is always safer to download _any_ file in binary mode,
just in case the ftp site's idea of ASCII isn't _your_ site's idea of what
ASCII is supposed to be. :D

It is also useful, when downloading files, to enter 'hash' as this lets you
see how fast the transfer is going. What happens is that '#' symbols get
displayed as the data is transfered, denoting (for example) 8K of data per
hash mark. On some programs, like ncftp, this isn't necessary, as a
'percentage-download-so-far- number is constantly shown. On programs like
ftp for Windows, it should display the number of bytes downloaded compared
to the actual file size, thus showing you how the transfer is progressing.
On Unix systems, perhaps in another XWindow, one can see how the transfer
is going by repeatedly entering 'ls -l' in the directory to which the ftp
site is sending the file. Watching for a few seconds will show how fast
the data is arriving and, hence, how long the transfer may take. Note that
transfer speed can vary considerably during any transfer, one minute going
fast and the next slow.

Anyway, on the example site I'm using here, to get to the Doom stuff, one
enters:

  cd pub/doom

When you do this, you get this (of course, if you ever try this site, like
as not the exact contents will have changed from the examples given here):


  250-Welcome to the greatest DOOM ftp server in the world!
  250-
  250-NEWSTUFF  - The NEWEST files are here.  Incoming is write only now.
  250-HELP      - Get the FTP faq and other help/support information
  250-text/faq  - Doom FAQ and others.
  250-wads      - User build WAD files for Registered DOOM only.
  250-sounds    - Replacement sounds for DOOM.
  250-wad_edit  - WAD file editors for Registered DOOM only.
  250-misc      - Anything else that just doesn't fit into these boxes.
  250-graphics  - Neato-nifty graphics patches for DOOM
  250-id        - Here is the shareware version of DOOM and upgrades
  250-deu       - Official USA site for DEU, greatest DOOM editor. 
  250-lmps      - Recorded games of people with no lives....
  250-incoming  - Put your new files here.  I move them around.
  250-doom2     - Files for the Doom ][ software.
  250-
  250-
  250-Send all suggestions to barry@noc.unt.edu
  250-
  250-THIS FILE MODIFIED 9.24.94
  250-
  250 CWD command successful.


Since this directory is a 'mirror' of the pub/doom directory on the
ftp.cdrom.com site, the above text is _exactly_ what you'd see if you ftp'd
to ftp.cdrom.com instead of the example site I'm using here.

Anyway, suppose I wanted to get an add-on level for Doom. Here is an example
session:


ftp> cd wads
  250-Welcome to the wads section:
  250-
  250-send all suggestions to barry@noc.unt.edu
  250-
  250-9-7-94
  250-
  250-/newwads is now the place to find the newest wads.  I'll update this
  250-note everytime I move stuff.  Also, check the ls-LR for this directory
  250-to get a complete list of just the wads.  Remember to check the /newwads2
  250-directory also.  Newwads2 contains all of Augusts submissions.  Newwads
  250-will have all of Septembers.
  250-
  250-
  250-
  250 CWD command successful.
  ftp> dir
  200 PORT command successful.
  150 Opening ASCII mode data connection for /bin/ls.
  total 139
  -r--r--r--   1 root     ftp           398 Sep 10 10:48 .message
  drwxr-xr-x   2 root     ftp          1024 Dec  3 06:29 1-9
  -r--r--r--   1 root     ftp          1052 Jul  1 16:27 HOW_TO_USE_WADS
  -r--r--r--   1 root     ftp           227 Jul 13 10:23 README
  drwxr-xr-x   2 root     ftp          5120 Dec  3 06:27 a-c
  drwxr-xr-x   2 root     ftp          1024 Sep 25 04:42 combos
  drwxr-xr-x   2 root     ftp          5120 Dec  3 06:54 d-f
  drwxr-xr-x   2 root     ftp          6144 Dec  3 06:15 deathmatch
  -r--r--r--   1 root     ftp         32875 Aug 15 23:14 dmrk0815.txt
  drwxr-xr-x   2 root     ftp          3072 Dec  3 07:01 g-i
  drwxr-xr-x   2 root     ftp          2048 Dec  3 07:00 j-l
  -r--r--r--   1 root     ftp         19202 Dec  2 12:16 ls-LR
  drwxr-xr-x   2 root     ftp          3072 Dec  3 06:59 m-o
  drwxr-xr-x   2 root     ftp          5120 Dec  3 07:33 newwads
  drwxr-xr-x   2 root     ftp          3072 Dec  3 07:33 newwads2
  drwxr-xr-x   2 root     ftp          3072 Dec  3 06:57 p-r
  drwxr-xr-x   2 root     ftp          1024 Dec  3 07:01 reviews
  drwxr-xr-x   2 root     ftp          6144 Dec  3 06:47 s-u
  drwxr-xr-x   2 root     ftp          1024 Dec  3 06:15 utility
  drwxr-xr-x   2 root     ftp          2048 Dec  4 05:26 v-z
  -r--r--r--   1 root     ftp         33567 Jul 24 11:07 wads0724.rev
  226 Transfer complete.
  1338 bytes received in 1 seconds (1.3 Kbytes/s)
  ftp> cd newwads
    250 CWD command successful.
  ftp> dir
  200 PORT command successful.
  150 Opening ASCII mode data connection for /bin/ls.
  total 8682
  -r--r--r--   1 root     ftp          6919 Oct  3 11:49 invade2.txt
  -r--r--r--   1 root     ftp        655718 Oct  4 07:36 invade2.zip
  -r--r--r--   1 root     ftp          1439 Oct  4 13:34 invepi2.txt
  -r--r--r--   1 root     ftp       1919191 Oct  4 13:37 invepi2.zip
  -r--r--r--   1 root     ftp          1439 Oct  4 13:04 invpro2.txt
  -r--r--r--   1 root     ftp       3119184 Oct  4 13:08 invpro2.zip
  -r--r--r--   1 root     ftp           752 Oct 22 23:40 quest12.txt
  -r--r--r--   1 root     ftp           182 Oct 23 01:07 quest12.zip
  -r--r--r--   1 root     ftp          3360 Sep 29 10:55 reactor3.txt
  -r--r--r--   1 root     ftp         21809 Sep 29 10:54 reactor3.zip
  -r--r--r--   1 root     ftp          2340 Nov 11 03:57 red.txt
  -r--r--r--   1 root     ftp         77252 Nov 11 03:58 red.zip
  -r--r--r--   1 root     ftp          2062 Oct 30 06:19 redroom.txt
  -r--r--r--   1 root     ftp         25277 Oct 30 06:19 redroom.zip
  -r--r--r--   1 root     ftp          2040 Oct  5 04:59 rot_e2m1.txt
  -r--r--r--   1 root     ftp        131886 Oct  5 05:11 rot_e2m1.zip
  -r--r--r--   1 root     ftp          4187 Nov 10 02:44 rrward02.txt
  -r--r--r--   1 root     ftp        225575 Nov 10 02:44 rrward02.zip
  -r--r--r--   1 root     ftp          2393 Oct 18 08:59 run666.txt
  -r--r--r--   1 root     ftp         67346 Oct 18 08:59 run666.zip
  -r--r--r--   1 root     ftp          3178 Oct 18 08:59 ry11ecr.txt
  -r--r--r--   1 root     ftp         68460 Oct 18 08:59 ry11ecr.zip
  -r--r--r--   1 root     ftp           349 Oct 25 00:27 sawtime.txt
  -r--r--r--   1 root     ftp        204243 Oct 25 00:35 sawtime.zip
  -r--r--r--   1 root     ftp         12408 Oct 30 22:48 serenity.txt
  -r--r--r--   1 root     ftp        405543 Oct 30 22:48 serenity.zip
  -r--r--r--   1 root     ftp          3223 Oct  4 21:22 sersound.txt
  -r--r--r--   1 root     ftp        801471 Oct  4 21:22 sersound.zip
  -r--r--r--   1 root     ftp          1554 Oct 23 18:28 sherhell.txt
  -r--r--r--   1 root     ftp        135457 Oct 23 18:23 sherhell.zip
  -r--r--r--   1 root     ftp          5547 Oct 24 16:38 shoots.txt
  -r--r--r--   1 root     ftp        152230 Oct 24 16:38 shoots.zip
  -r--r--r--   1 root     ftp          2034 Oct 15 04:36 statx2.txt
  -r--r--r--   1 root     ftp         50226 Oct 15 04:38 statx2.zip
  -r--r--r--   1 root     ftp          1612 Oct 14 21:14 straw.txt
  -r--r--r--   1 root     ftp         62731 Oct 14 21:14 straw.zip
  -r--r--r--   1 root     ftp         60513 Oct 28 06:50 straw2.zip
  -r--r--r--   1 root     ftp         60804 Oct 28 07:09 straw3.zip
  -r--r--r--   1 root     ftp            16 Oct 28 07:26 straw4.zip
  -r--r--r--   1 root     ftp            16 Oct 29 06:08 straw6.zip
  -r--r--r--   1 root     ftp          1853 Nov 16 02:03 switches.txt
  -r--r--r--   1 root     ftp         38501 Nov 16 02:03 switches.zip
  -r--r--r--   1 root     ftp          2793 Nov 16 22:29 tmatch-1.txt
  -r--r--r--   1 root     ftp         16581 Nov 16 22:29 tmatch-1.zip
  -r--r--r--   1 root     ftp          3335 Oct 13 09:56 tripwire.txt
  -r--r--r--   1 root     ftp         34080 Oct 13 09:56 tripwire.zip
  -r--r--r--   1 root     ftp          4140 Oct 28 21:55 uac-hq.txt
  -r--r--r--   1 root     ftp        159356 Oct 28 22:10 uac-hq.zip
  -r--r--r--   1 root     ftp          1134 Nov 12 21:14 walzhaus.txt
  -r--r--r--   1 root     ftp        111546 Nov 12 21:14 walzhaus.zip
  -r--r--r--   1 root     ftp            95 Nov 17 21:21 wetwrkd1.txt
  -r--r--r--   1 root     ftp         65892 Nov 17 21:19 wetwrkd1.zip
  -r--r--r--   1 root     ftp          2187 Nov 10 20:50 xmas.txt
  -r--r--r--   1 root     ftp         55828 Nov 10 20:50 xmas.zip
  226 Transfer complete.
  3676 bytes received in 4.7 seconds (0.76 Kbytes/s)
  ftp> bin
  200 Type set to I.
  ftp> hash
  Hash mark printing on (8192 bytes/hash mark).
  ftp> get wetwrkd1.zip
  200 PORT command successful.
  150 Opening BINARY mode data connection for wetwrkd1.zip (65892 bytes).
  ##########################################################################
  ###################################
  226 Transfer complete.
  local: wetwrkd1.zip remote: wetwrkd1.zip
  65892 bytes received in 34 seconds (1.9 Kbytes/s)
  ftp> close
  221 Goodbye.
  ftp> quit
  brahma%


So, that's how one gets a file via ftp.

Incidentally, I downloaded the *same* file from a different site in Europe
(Sweden instead of Austria) and I got this:

  ftp> get wetwrkd1.zip
  200 PORT command successful.
  150 Opening BINARY mode data connection for wetwrkd1.zip (65892 bytes).
  ##########################################################################
  ###################################
  226 Transfer complete.
  local: wetwrkd1.zip remote: wetwrkd1.zip
  65892 bytes received in 10 seconds (6.2 Kbytes/s)

As you can see, the speed of ftp sites varies greatly. ftp.luth.se can
transfer as fast as 100K/second, while some sites I've tried to use are so
slow (less than 100 bytes/second) that I just stop the ftp and try somewhere
else. The load on a site varies greatly and it is best to access a site
when the local time of the country the site is based in is in the early
hours of the morning (i.e. people in the U.K. should access USA sites around
10am U.K. time because that is when most folk in the USA are asleep (10am
GMT would be anything from 2am to 5am US time, depending on time zone).


Anyway, here are a couple of other things about using anonymous ftp:

- Most sites will let you enter 'ftp' instead of 'anonymous' as login name,
  which saves typing and errors. :D

- Most sites will let you abbreviate your email address to just your name
  followed by the '@' symbol (so I would enter 'mapleson@' for instance,
  minus the quotes of course).

- Most sites don't care if you don't bother entering 'close' before
  entering 'quit'. I never enter 'close' and I've not had any problems yet.
  You can also enter 'bye' which seems to be identical to 'quit', probably
  for the sake of backwards compatability.

- It is always best to use binary mode for transfering *anything*, even if
  the file is just ASCII text. It's more reliable as one can never be quite
  sure what the ftp site's idea of an ASCII file is! :D


                   ---------------< Part 2 >---------------

                How to upload (ie. send) files to an ftp site.

Note for Doom PWAD writers: there is a standardised 'PWAD Template' form which
you can upload as a .txt file to accompany your zipped PWAD. The template file
can be downloaded as a zip file from ftp.cdrom.com or any of its mirror sites.
The directory on ftp.cdrom.com is:

  pub/doom/docs/editing

and the file is:

  wadtempt.zip

There is an accompanying text file called:

  wadtempt.txt

- End of note for PWAD authors.

Uploading files.
^^^^^^^^^^^^^^^^

This process is no more complicated than receiving files. The first thing
to do is to make sure you are in the right directory when running the ftp
program, ie. the directory on your computer that contains the file(s) you
want to upload. For Windows ftp programs, this probably just means using
the file browser, etc. 
Next you ftp to the intended site just as before, using 'ftp' or 'anonymous'
as a login name, email address as password, etc.

On most sites, depending on what you're wanting to upload, there will be a
specific directory on the site where uploads are supposed to be placed.
Usually, this directory will be called 'incoming'. In the example Doom site
above, the appropriate directory for uploading Doom stuff is
pub/doom/incoming. It's important that you find the right place to upload
your file.

Now enter 'bin' and 'hash' as usual (minus the quotes). There are two
commands to upload files, 'send' and 'put'. As far as I can tell, there is
no difference between them. On Windows ftp programs this is irrelevant of
course as one would just click on a button to send the file.

So, one might enter:

  send myfile.zip

or something similar. As before, the file will transfer at whatever speed
and hash marks (if using a command style ftp program) will appear as the
transfer progresses.

For uploading files, the MOST important thing is to ALWAYS upload in
_binary_ mode. Many people get justifiably annoyed when they download a
large file (a Doom PWAD add-on level, for instance) and find that it is
useless because the author of the file forgot to upload the file in binary
mode. So, remember this as it's very important.

It is accepted practice, and a sensible practice at that, to always
upload a text file with whatever you uploaded which explains what the
upload actually is, who wrote it, how to use it, etc. Such 'README' type
files usually end in '.txt'. So, if I uploaded a Doom add-on level called
'diehard.zip', then I should upload a file called 'diehard.txt' which
explains what the 'diehard.zip' file actually is.

Of course, if the main file you're actually sending is purely text, then
an accompanying .txt file probably isn't necessary (unless the main file
is quite large. An example is the Doom FAQ - that has a .txt file).

After sending files, one exits ftp in the usual manner via 'quit' or
'close', etc.


Final notes:
^^^^^^^^^^^^

There are some other quite useful commands to bare in mind when using ftp.
Some may or may not be relevant to Windows style fpt programs.

The first is the 'lcd' command, which allows you to change the current
directory on _your_ site, without exiting the ftp program. Useful if you
find you've started the ftp session in the wrong directory. So, for
instance, you might enter:

  lcd ..

A message will appear telling you your new directory path.

Earlier, I mentioned that there are two seemingly identical commands for
sending files. This is also the case for retrieving files: the identical
command to 'get' is 'recv'. I suspect these identical commands exist in
command-line based ftp programs in order to maintain compatability with
older ftp standards.

Another useful command is one which allows you to view a _text_ file only
from within the ftp program (this applies to command line based ftp
programs only). You'd enter something like:

  recv filename.txt |more

This will get the text file and pipe it through the 'more' program, thus
displaying the file on your screen in the usual more-style manner ('press
space to continue' messages appearing, etc. Press CTRL-C to quite the
'more' listing in the usual manner). Note that there must _not_ be a
space betweeb the pipe '|' symbol and the word 'more'.

When you use recv in the above manner, the file does _not_ get saved to
your directory. It's just a way of seeing the contents of a file on a site
without committing yourself to actually downloading it.

Multiple files.
^^^^^^^^^^^^^^^

It is possible to send and receive more than one file at once when using
ftp. Thus, for instance, suppose a directory on a NASA site contained loads
of astronomy images of the recent comet impact on Jupiter. The
image files might be named thusly:

  impact00.jpg
  impact01.jpg
  impact02.jpg
  impact03.jpg
  impact04.jpg
       .
       .
       .

and so on. It would be rather laborious to enter 'get <filename>' for each
individual file; so, instead, you can enter a single command to get the
lot. The command for this is 'mget'. This will allow you to get more than
one file at a time via the use of wildcards. Hence, to download ALL the
pictures in one go, you would enter:

  mget impact*.jpg

or just:

  mget impact*.*

Try to be as specific as possible when using wildcards like this, to ensure
that you don't download files which you don't want.

Note that, depending on the default settings of your ftp program, you may
or may not get 'prompted' for each file with a message that says something
like:

  Retrieve file 'impact00.jpg'? (Y/N) : 
                                       ^
Again, it's a pain to have to enter 'Y' about 30 times, so if you're sure
you want them all, you can enter:

  prompt

before you enter the 'mget' command. This will toggle whether or not you are
prompted for confirmation during mget operations. To see whether multiple-
file-prompting is on or off, enter:

  status

This will display various items of information about the current status
of the ftp session. For instance (just running the ftp program without
connecting anywhere):

  brahma% ftp
  ftp> status
  Not connected.
  No proxy connection.
  Mode: stream; Type: ascii; Form: non-print; Structure: file
  Verbose: on; Bell: off; Prompting: off; Globbing: on
  Store unique: off; Receive unique: off
  Case: off; CR stripping: on
  Ntrans: off
  Nmap: off
  Hash mark printing: off; Use of PORT cmds: on
  ftp> quit

The prompting status is shown as he 3rd item on the 4th line of status
information.

There are a number of other ftp commands, most of which you'll probably
never use, or rarely anyway. Some are just shortcuts, for instance you
can enter:

  cdup

instead of:

  cd ..

A complete list of commands can be seen by entering 'help'. eg.

  ftp> help
  Commands may be abbreviated.  Commands are:

  !               cr              macdef          proxy           send
  $               delete          mdelete         sendport        status
  account         debug           mdir            put             struct
  append          dir             mget            pwd             sunique
  ascii           disconnect      mkdir           quit            tenex
  bell            form            mls             quote           trace
  binary          get             mode            recv            type
  bye             glob            mput            remotehelp      user
  case            hash            nmap            rename          verbose
  cd              help            ntrans          reset           ?
  cdup            lcd             open            rmdir
  close           ls              prompt          runique

You can find out what a command is by entering:

  help <command>

eg.

  ftp> help ntrans
  ntrans          set translation table for default file name mapping

What the hell _that_ means I have no idea! :D But anyway... :) Actually, you
can read about this command in the man page given at the end of this help
file. It may be useful for Unix users who are ftp'ing to a non-Unix site. I
haven't had reason to use it yet, but you never know.

The information you receive when using the 'help' command in the above manner
tends to be very brief, for example:

  ftp> help mget
  mget            get multiple files

Not much info there. :\ This is the main reason that I have written this help
file. I hope you find it useful.


And that's it, I guess. If you're using Unix, there should be a manual page
about ftp, which I have included below, so I will leave you with that. It has
much more information on the various commands than the on-line help within
ftp program has, so it is well worth a read, even if you're not using a Unix
system. It also lists all the various initial command line options.

If you have any further questions on ftp, please email me and I will attempt
to answer them and also update this file with said questions and answers.

Byeee! :)

Ian.

The Doom Help Service (DHS).
Co-ordinator of rec.games.computer.doom.help.

WWW addresses:   

  Home page:     http://www.cee.hw.ac.uk/~mapleson/
  DHS:           http://www.cee.hw.ac.uk/~mapleson/doom/doom.html
  Help Archive:  http://www.cee.hw.ac.uk/~mapleson/doom/doomhelp.zip
  Dissertation:  http://www.cee.hw.ac.uk/~mapleson/diss/diss.html
  SGI Stuff:     http://www.cee.hw.ac.uk/~mapleson/sgistuff/sgindex.html

PS. Oh, these 'http' things refer to the World Wide Web. If you want info on
that, email me.


)*----------------- Manual page for 'ftp'.... ---------------------------

brahma% man ftp
Reformatting page.  Wait... done
NAME
     ftp - file transfer program

SYNOPSIS
     ftp [ -dgintv ] [ hostname ]

AVAILABILITY
     This command  is  available  with  the  Networking  software
     installation  option.   Refer  to  Installing  SunOS 4.1 for
     information on how to install optional software.

DESCRIPTION
     ftp is the user  interface  to  the  ARPANET  standard  File
     Transfer  Protocol (FTP).  ftp transfers files to and from a
     remote network site.

     The client host with which ftp  is  to  communicate  may  be
     specified on the command line.  If this is done, ftp immedi-
     ately attempts to establish a connection to an FTP server on
     that host; otherwise, ftp enters its command interpreter and
     awaits instructions from the user.   When  ftp  is  awaiting
     commands from the user, it displays the prompt `ftp>'.

OPTIONS
     Options may be specified at the command line, or to the com-
     mand interpreter.

     -d   Enable debugging.

     -g   Disable filename "globbing."

     -i   Turn off interactive  prompting  during  multiple  file
          transfers.

     -n   Do not attempt "auto-login"  upon  initial  connection.
          If auto-login is enabled, ftp checks the .netrc file in
          the user's home directory for an  entry  describing  an
          account on the remote machine.  If no entry exists, ftp
          will prompt for the login name of the  account  on  the
          remote  machine  (the  default is the login name on the
          local machine), and, if necessary, prompts for a  pass-
          word and an account with which to login.

     -t   Enable packet tracing (unimplemented).

     -v   Show all responses from the remote server, as  well  as
          report  on data transfer statistics.  This is turned on
          by default if ftp is  running  interactively  with  its
          input coming from the user's terminal.

     ! [ command ]
          Run command as a shell command on  the  local  machine.
          If no command is given, invoke an interactive shell.

     $ macro-name [ args ]
          Execute the macro macro-name that was defined with  the
          macdef  command.   Arguments  are  passed  to the macro
          unglobbed.

     account [ passwd ]
          Supply a supplemental password  required  by  a  remote
          system  for  access  to resources once a login has been
          successfully completed.  If no  argument  is  included,
          the  user will be prompted for an account password in a
          non-echoing input mode.

     append local-file [ remote-file ]
          Append a local file to a file on  the  remote  machine.
          If remote-file is left unspecified, the local file name
          is used in naming the remote file after  being  altered
          by  any ntrans or nmap setting.  File transfer uses the
          current  settings  for  "representation  type",   "file
          structure", and "transfer mode".

     ascii
          Set the "representation type"  to  "network  "  ASCII".
          This is the default type.

     bell Sound a bell after each file transfer command  is  com-
          pleted.

     binary
          Set the "representation type" to "image".

     bye  Terminate the FTP session with the  remote  server  and
          exit  ftp.   An EOF will also terminate the session and
          exit.

     case Toggle remote computer file name  case  mapping  during
          mget  commands.   When  case  is  on  (default is off),
          remote computer file names with all  letters  in  upper
          case  are  written  in  the  local  directory  with the
          letters mapped to lower case.

     cd remote-directory
          Change the working directory on the remote  machine  to
          remote-directory.

     cdup Change the remote  machine  working  directory  to  the
          parent of the current remote machine working directory.

     close
          Terminate the FTP session with the remote  server,  and
          return  to the command interpreter.  Any defined macros
          are erased.

     cr   Toggle RETURN stripping during "network "  ASCII"  type
          file    retrieval.     Records   are   denoted   by   a
          RETURN/LINEFEED sequence during "network " ASCII"  type
          file  transfer.   When  cr  is on (the default), RETURN
          characters are stripped from this sequence  to  conform
          with  the UNIX system single LINEFEED record delimiter.
          Records on non-UNIX-system  remote  hosts  may  contain
          single  LINEFEED  characters; when an "network " ASCII"
          type transfer is made, these LINEFEED characters may be
          distinguished  from  a record delimiter only when cr is
          off.

     delete remote-file
          Delete the file remote-file on the remote machine.

     debug [ debug-value ]
          Toggle debugging mode. If an  optional  debug-value  is
          specified  it is used to set the debugging level.  When
          debugging is on, ftp prints each command  sent  to  the
          remote machine, preceded by the string `-->'.

     dir [ remote-directory ] [ local-file ]
          Print a listing of the directory contents in the direc-
          tory,  remote-directory,  and,  optionally, placing the
          output in local-file.  If no  directory  is  specified,
          the  current working directory on the remote machine is
          used.  If no local file is specified, or local-file  is
          `-', output is sent to the terminal.

     disconnect
          A synonym for close.

     form [ format-name ]
          Set  the  carriage  control  format  subtype   of   the
          "representation  type"  to format-name.  The only valid
          format-name is  non-print,  which  corresponds  to  the
          default "non-print" subtype.

     get remote-file [ local-file ]
          Retrieve the remote-file and  store  it  on  the  local
          machine.   If  the local file name is not specified, it
          is given the same name it has on  the  remote  machine,
          subject  to alteration by the current case, ntrans, and
          nmap settings.  The current settings  for  "representa-
          tion  type",  "file structure", and "transfer mode" are
          used while transferring the file.

     glob Toggle filename expansion, or "globbing", for  mdelete,
          mget  and  mput.   If globbing is turned off, filenames
          are taken literally.

          Globbing for mput is done as in  csh(1).   For  mdelete
          and  mget, each remote file name is expanded separately
          on the remote machine, and the lists are not merged.

          Expansion of a directory name is likely to be radically
          different  from  expansion  of  the name of an ordinary
          file: the exact result depends on the remote  operating
          system  and  FTP  server, and can be previewed by doing
          `mls remote-files -'.

          mget and mput are not meant to transfer  entire  direc-
          tory  subtrees  of files.  You can do this by transfer-
          ring  a  tar(1)  archive  of  the  subtree   (using   a
          "representation  type"  of "image" as set by the binary
          command).

     hash Toggle hash-sign  (#)  printing  for  each  data  block
          transferred.

     help [ command ]
          Print an informative message about the meaning of  com-
          mand.   If  no  argument is given, ftp prints a list of
          the known commands.

     lcd [ directory ]
          Change the working directory on the local machine.   If
          no directory is specified, the user's home directory is
          used.

     ls [ remote-directory ] [ local-file ]
          Print an abbreviated  listing  of  the  contents  of  a
          directory  on  the remote machine.  If remote-directory
          is left unspecified, the current working  directory  is
          used.   If no local file is specified, or if local-file
          is `-', the output is sent to the terminal.

     macdef macro-name
          Define a macro.  Subsequent lines  are  stored  as  the
          macro  macro-name;  a  null  line  (consecutive NEWLINE
          characters in a file or RETURN characters from the ter-
          minal)  terminates  macro input mode.  There is a limit
          of 16 macros and 4096 total characters in  all  defined
          macros.  Macros remain defined until a close command is
          executed.

          The macro processor interprets `$' and `\'  as  special
          characters.  A `$' followed by a number (or numbers) is
          replaced by the corresponding  argument  on  the  macro
          invocation  command  line.   A  `$'  followed by an `i'
          signals that macro processor that the  executing  macro
          is  to be looped. On the first pass `$i' is replaced by
          the first argument  on  the  macro  invocation  command
          line,  on  the second pass it is replaced by the second
          argument, and so on.  A `\' followed by  any  character
          is  replaced by that character.  Use the `\' to prevent
          special treatment of the `$'.

     mdelete [ remote-files ]
          Delete the remote-files on the remote machine.

     mdir remote-files local-file
          Like dir, except multiple remote files  may  be  speci-
          fied.   If interactive prompting is on, ftp will prompt
          the user to verify that the last argument is indeed the
          target local file for receiving mdir output.

     mget remote-files
          Expand the remote-files on the remote machine and do  a
          get  for  each  file  name thus produced.  See glob for
          details on  the  filename  expansion.   Resulting  file
          names will then be processed according to case, ntrans,
          and nmap settings.   Files  are  transferred  into  the
          local  working  directory,  which  can  be changed with
          `lcd directory'; new local directories can  be  created
          with `! mkdir directory'.

     mkdir directory-name
          Make a directory on the remote machine.

     mls remote-files local-file
          Like ls(1V), except multiple remote files may be speci-
          fied.   If interactive prompting is on, ftp will prompt
          the user to verify that the last argument is indeed the
          target local file for receiving mls output.

     mode [ mode-name ]
          Set the "transfer mode" to mode-name.  The  only  valid
          mode-name  is  stream, which corresponds to the default
          "stream" mode.

     mput local-files
          Expand wild cards in the list of local files  given  as
          arguments  and  do a put for each file in the resulting
          list.  See glob  for  details  of  filename  expansion.
          Resulting  file  names will then be processed according
          to ntrans and nmap settings.

     nmap [ inpattern outpattern ]
          Set or unset the filename  mapping  mechanism.   If  no
          arguments are specified, the filename mapping mechanism
          is unset.  If arguments are specified, remote filenames
          are mapped during mput commands and put commands issued
          without a specified remote target filename.   If  argu-
          ments  are specified, local filenames are mapped during
          mget commands and get commands issued without a  speci-
          fied local target filename.

          This command is useful when connecting to  a  non-UNIX-
          system  remote  host with different file naming conven-
          tions or practices.  The mapping  follows  the  pattern
          set  by  inpattern and outpattern.  inpattern is a tem-
          plate for incoming filenames (which  may  have  already
          been  processed  according  to the ntrans and case set-
          tings).  Variable templating is accomplished by includ-
          ing  the sequences $1, $2, ..., $9 in inpattern.  Use \
          to prevent this special treatment of the  $  character.
          All  other  characters  are  treated literally, and are
          used to determine the nmap inpattern variable values.

          For example, given inpattern $1.$2 and the remote  file
          name mydata.data, $1 would have the value "mydata", and
          $2 would have the value "data".

          The  outpattern   determines   the   resulting   mapped
          filename.   The  sequences $1, $2, ..., $9 are replaced
          by any value resulting  from  the  inpattern  template.
          The  sequence  $0 is replaced by the original filename.
          Additionally, the sequence `[seq1,seq2]' is replaced by
          seq1  if  seq1  is  not  a null string; otherwise it is
          replaced by seq2.

          For    example,    the    command    `nmap     $1.$2.$3
          [$1,$2].[$2,file]'  would  yield  the  output  filename
          myfile.data  for  input   filenames   myfile.data   and
          myfile.data.old,  myfile.file  for  the  input filename
          myfile,  and  myfile.myfile  for  the  input   filename
          .myfile.   SPACE  characters may be included in outpat-
          tern, as in the example `nmap $1 |  sed  "s/   *$//"  >
          $1'.   Use the \ character to prevent special treatment
          of the `$', `[', `]' and `,' characters.

     ntrans [ inchars [ outchars ] ]
          Set or unset the filename character translation mechan-
          ism.  If no arguments are specified, the filename char-
          acter translation mechanism is unset.  If arguments are
          specified,   characters   in   remote   filenames   are
          translated during mput commands and put commands issued
          without a specified remote target filename, and charac-
          ters in local  filenames  are  translated  during  mget
          commands  and  get  commands issued without a specified
          local target filename.

          This command is useful when connecting to  a  non-UNIX-
          system  remote  host with different file naming conven-
          tions or practices.  Characters in a filename  matching
          a   character   in   inchars   are  replaced  with  the
          corresponding   character   in   outchars.    If    the
          character's  position  in  inchars  is  longer than the
          length of outchars, the character is deleted  from  the
          file name.

     open host [ port ]
          Establish  a  connection  to  the  specified  host  FTP
          server.   An  optional  port number may be supplied, in
          which case, ftp will attempt to contact an  FTP  server
          at   that   port.   If  the  auto-login  option  is  on
          (default), ftp will also attempt to  automatically  log
          the user in to the FTP server (see below).

     prompt
          Toggle  interactive  prompting.  Interactive  prompting
          occurs during multiple file transfers to allow the user
          to selectively retrieve or store  files.   By  default,
          prompting  is  turned  on.  If prompting is turned off,
          any mget or mput  will  transfer  all  files,  and  any
          mdelete will delete all files.

     proxy ftp-command
          Execute an FTP command on a secondary  control  connec-
          tion.   This  command allows simultaneous connection to
          two remote FTP servers for transferring  files  between
          the  two servers.  The first proxy command should be an
          open, to establish the  secondary  control  connection.
          Enter  the  command `proxy ?' to see other FTP commands
          executable on the secondary connection.

          The following commands behave differently when prefaced
          by  proxy:  open  will not define new macros during the
          auto-login process, close will not erase existing macro
          definitions,  get and mget transfer files from the host
          on the primary control connection to the  host  on  the
          secondary control connection, and put, mput, and append
          transfer files from the host on the  secondary  control
          connection  to  the host on the primary control connec-
          tion.

          Third party file transfers depend upon support  of  the
          PASV  command  by  the  server on the secondary control
          connection.

     put local-file [ remote-file]
          Store a local file on the remote machine.   If  remote-
          file  is  left unspecified, the local file name is used
          after processing according to any ntrans or  nmap  set-
          tings  in  naming  the remote file.  File transfer uses
          the current settings for "representation  type",  "file
          structure", and "transfer mode".

     pwd  Print the name of the current working directory on  the
          remote machine.

     quit A synonym for bye.

     quote arg1 arg2 ...
          Send the arguments specified, verbatim, to  the  remote
          FTP  server.   A  single  FTP reply code is expected in
          return.

     recv remote-file [ local-file]
          A synonym for get.

     remotehelp [ command-name ]
          Request  help  from  the  remote  FTP  server.   If   a
          command-name  is specified it is supplied to the server
          as well.

     rename from to
          Rename the file from on the remote machine to have  the
          name to.

     reset
          Clear  reply  queue.   This   command   re-synchronizes
          command/reply  sequencing  with  the remote FTP server.
          Resynchronization may be necessary following  a  viola-
          tion of the FTP protocol by the remote server.

     rmdir directory-name
          Delete a directory on the remote machine.

     runique
          Toggle storing of files on the local system with unique
          filenames.   If a file already exists with a name equal
          to the target local filename for a get or mget command,
          a  `.1' is appended to the name.  If the resulting name
          matches another existing file, a `.2'  is  appended  to
          the  original  name.   If  this process continues up to
          `.99', an error message is printed,  and  the  transfer
          does  not  take  place.   The generated unique filename
          will be reported.  Note: runique will not affect  local
          files  generated from a shell command (see below).  The
          default value is off.

     send local-file [ remote-file ]
          A synonym for put.

     sendport
          Toggle the use of PORT commands.  By default, ftp  will
          attempt  to use a PORT command when establishing a con-
          nection for each data transfer.  The use of  PORT  com-
          mands  can prevent delays when performing multiple file
          transfers. If the PORT command fails, ftp will use  the
          default  data  port.  When  the use of PORT commands is
          disabled, no attempt will be made to use PORT  commands
          for  each data transfer.  This is useful when connected
          to certain FTP implementations that  ignore  PORT  com-
          mands but incorrectly indicate they have been accepted.

     status
          Show the current status of ftp.

     struct [ struct-name ]
          Set the "file  structure"  to  struct-name.   The  only
          valid  struct-name  is  file,  which corresponds to the
          default "file" structure.

     sunique
          Toggle storing of files on remote machine under  unique
          file  names.   The  remote  FTP server must support the
          STOU command for  successful  completion.   The  remote
          server  will  report the unique name.  Default value is
          off.

     tenex
          Set the "representation type" to that needed to talk to
          TENEX machines.

     trace
          Toggle packet tracing (unimplemented).

     type [ type-name ]
          Set the "representation type" to type-name.  The  valid
          type-names  are  ascii for "network " ASCII", binary or
          image for "image", and tenex for "local byte size" with
          a  byte size of 8 (used to talk to TENEX machines).  If
          no type is specified, the current type is printed.  The
          default type is "network " ASCII".

     user user-name [ password ] [ account ]
          Identify yourself to the  remote  FTP  server.  If  the
          password  is  not specified and the server requires it,
          ftp will prompt the user for it (after disabling  local
          echo).   If  an account field is not specified, and the
          FTP server requires it, the user will be  prompted  for
          it.   If  an  account  field  is  specified, an account
          command will be relayed to the remote server after  the
          login  sequence  is  completed if the remote server did
          not require it for logging in.  Unless ftp  is  invoked
          with   "auto-login"  disabled,  this  process  is  done
          automatically on initial connection to the FTP server.

     verbose
          Toggle verbose mode.  In verbose  mode,  all  responses
          from  the  FTP  server  are  displayed to the user.  In
          addition, if verbose mode is on, when a  file  transfer
          completes,  statistics  regarding the efficiency of the
          transfer are reported. By default, verbose mode  is  on
          if  ftp's  commands are coming from a terminal, and off
          otherwise.

     ? [ command ]
          A synonym for help.

     Command arguments which have embedded spaces may  be  quoted
     with quote (") marks.

     If any command argument which  is  not  indicated  as  being
     optional  is  not  specified, ftp will prompt for that argu-
     ment.

ABORTING A FILE TRANSFER
     To abort a file transfer, use  the  terminal  interrupt  key
     (usually  CTRL-C).  Sending  transfers  will  be immediately
     halted.  Receiving transfers will be halted by sending a ftp
     protocol  ABOR  command to the remote server, and discarding
     any further data received.   The  speed  at  which  this  is
     accomplished  depends  upon  the remote server's support for
     ABOR processing.  If the remote server does not support  the
     ABOR  command,  an  "ftp>"  prompt will not appear until the
     remote server has completed sending the requested file.

     The terminal interrupt key sequence will be ignored when ftp
     has  completed  any local processing and is awaiting a reply
     from the remote server.  A  long  delay  in  this  mode  may
     result  from  the  ABOR  processing described above, or from
     unexpected behavior by the remote server,  including  viola-
     tions  of the ftp protocol.  If the delay results from unex-
     pected remote server behavior, the local ftp program must be
     killed by hand.

FILE NAMING CONVENTIONS
     Local files specified as arguments to ftp commands are  pro-
     cessed according to the following rules.

     1)   If the file name `-' is specified, the  standard  input
          (for reading) or standard output (for writing) is used.

     2)   If the first character of the file  name  is  `|',  the
          remainder  of  the  argument  is interpreted as a shell
          command.  ftp then forks a shell, using popen(3S)  with
          the  argument  supplied,  and  reads  (writes) from the
          standard output (standard input) of that shell.  If the
          shell  command  includes SPACE characters, the argument
          must be quoted; for example `"| ls -lt"'.   A  particu-
          larly  useful  example  of  this  mechanism  is: `dir |
          more'.

     3)   Failing the above checks,  if  "globbing"  is  enabled,
          local  file  names  are expanded according to the rules
          used in the csh(1); see the glob command.  If  the  ftp
          command expects a single local file (for example, put),
          only the first filename  generated  by  the  "globbing"
          operation is used.

     4)   For mget commands and  get  commands  with  unspecified
          local  file  names,  the  local  filename is the remote
          filename, which may be altered by a  case,  ntrans,  or
          nmap  setting.   The  resulting  filename  may  then be
          altered if runique is on.

     5)   For mput commands and  put  commands  with  unspecified
          remote  file  names,  the  remote filename is the local
          filename, which may be altered by a ntrans or nmap set-
          ting.   The  resulting  filename may then be altered by
          the remote server if sunique is on.

FILE TRANSFER PARAMETERS
     The FTP specification specifies many  parameters  which  may
     affect a file transfer.

     The "representation type" may be one of "network  "  ASCII",
     "EBCDIC",  "image",  or  "local  byte size" with a specified
     byte size (for PDP-10's and PDP-20's mostly).  The  "network
     "  ASCII"  and  "EBCDIC"  types have a further subtype which
     specifies whether vertical format control  (NEWLINE  charac-
     ters,  form  feeds,  etc.)  are  to be passed through ("non-
     print"), provided in  TELNET  format  ("TELNET  format  con-
     trols"),  or  provided  in  ASA (FORTRAN) ("carriage control
     (ASA)") format.  ftp supports the "network " ASCII" (subtype
     "non-print"  only) and "image" types, plus "local byte size"
     with a byte size of 8 for communicating with TENEX machines.

     The "file structure" may be one of "file" (no record  struc-
     ture),  "record",  or "page".  ftp supports only the default
     value, which is "file".

     The "transfer mode" may be  one  of  "stream",  "block",  or
     "compressed".  ftp supports only the default value, which is
     "stream".

SEE ALSO
     csh(1),  ls(1V),  rcp(1C),  tar(1),   popen(3S),   netrc(5),
     ftpd(8C)

BUGS
     Correct execution  of  many  commands  depends  upon  proper
     behavior by the remote server.

     An error in the treatment of carriage returns in the 4.2 BSD
     code  handling  transfers  with  a  "representation type" of
     "network " ASCII" has been corrected.  This  correction  may
     result  in  incorrect  transfers of binary files to and from
     4.2 BSD servers using a "representation type" of "network  "
     ASCII". Avoid this problem by using the "image" type.

