1397 lines
33 KiB
Groff
1397 lines
33 KiB
Groff
.\"-------
|
|
.\" Man page portability notes
|
|
.\"
|
|
.\" These are some notes on conventions to maintain for greatest
|
|
.\" portability of this man page to various other versions of
|
|
.\" nroff.
|
|
.\"
|
|
.\" When you want a \ to appear in the output, use \e in the man page.
|
|
.\" (NOTE this comes up in the rc grammar, where to print out '\n' the
|
|
.\" man page must contain '\en'.)
|
|
.\"
|
|
.\" Evidently not all versions of nroff allow the omission of the
|
|
.\" terminal " on a macro argument. Thus what could be written
|
|
.\"
|
|
.\" .Cr "exec >[2] err.out
|
|
.\"
|
|
.\" in true nroffs must be written
|
|
.\"
|
|
.\" .Cr "exec >[2] err.out"
|
|
.\"
|
|
.\" instead.
|
|
.\"
|
|
.\" Use symbolic font names (e.g. R, I, B) instead of the standard
|
|
.\" font positions 1, 2, 3. Note that for Xf to work the standard
|
|
.\" font names must be single characters.
|
|
.\"
|
|
.\" Note that sentences should end at the end of a line. nroff and
|
|
.\" troff will supply the correct intersentence spacing, but only if
|
|
.\" the sentences end at the end of a line. Explicit spaces, if given,
|
|
.\" are apparently honored and the normal intersentence spacing is
|
|
.\" supressed.
|
|
.\"
|
|
.\" DaviD W. Sanderson
|
|
.\"-------
|
|
.\" Dd distance to space vertically before a "display"
|
|
.\" These are what n/troff use for interparagraph distance
|
|
.\"-------
|
|
.if t .nr Dd .4v
|
|
.if n .nr Dd 1v
|
|
.\"-------
|
|
.\" Sp space down the interparagraph distance
|
|
.\"-------
|
|
.de Sp
|
|
.sp \\n(Ddu
|
|
..
|
|
.\"-------
|
|
.\" Ds begin a display, indented .5 inches from the surrounding text.
|
|
.\"
|
|
.\" Note that uses of Ds and De may NOT be nested.
|
|
.\"-------
|
|
.de Ds
|
|
.Sp
|
|
.in +0.5i
|
|
.nf
|
|
..
|
|
.\"-------
|
|
.\" De end a display (no trailing vertical spacing)
|
|
.\"-------
|
|
.de De
|
|
.fi
|
|
.in
|
|
..
|
|
.TH NcFTP 1 "" NCEMRSoft
|
|
.\"-------
|
|
.SH "NAME"
|
|
.\"-------
|
|
NcFTP \(em Internet file transfer program
|
|
.\"-------
|
|
.SH "SYNOPSIS"
|
|
.\"-------
|
|
.B ncftp
|
|
.RI [ "program options" ]
|
|
.RI [[ "open options" ]
|
|
.IR hostname [\c
|
|
.B :\c
|
|
.IR pathname ]]
|
|
.\"-------
|
|
.SH "DESCRIPTION"
|
|
.\"-------
|
|
.I NcFTP
|
|
is a user interface to the Internet standard
|
|
.IR "File Transfer Protocol" .
|
|
This program allows a user to transfer files to and from a remote network
|
|
site, and offers additional features that are not found in the standard
|
|
interface,
|
|
.IR ftp .
|
|
.\"-------
|
|
.SH "FEATURES"
|
|
.\"-------
|
|
Program options will be explained later in this document.
|
|
Let's get down to business and go over the features
|
|
that make this program worthwhile.
|
|
.PP
|
|
Here is the list of section headers; I have my $MANPAGER environment
|
|
variable set to use
|
|
.RB `` "less \-i" ''
|
|
so that I can skip to the section I
|
|
want (otherwise,
|
|
.BI / regex
|
|
commands to the pager won't match the section
|
|
headers because of the formatting codes;
|
|
the
|
|
.RB `` \-i ''
|
|
can search through the formatting codes)
|
|
.Ds
|
|
Establishing the remote connection
|
|
Format of the RC file
|
|
The Recent-sites file
|
|
Redialing a busy remote site
|
|
Supplying a sitename from your shell's command line
|
|
Using Colon-mode
|
|
Using FTP-cat and FTP-more mode
|
|
Supplying a port number with the open command
|
|
Displaying and changing program variables
|
|
Program variables
|
|
Listing a remote directory
|
|
Viewing a remote directory with your pager
|
|
Redisplaying the last directory listing
|
|
Fetching files from the remote host
|
|
Viewing a remote file with your pager
|
|
Creating a message file on the remote host
|
|
Looking up site names and addresses
|
|
Checking the configuration of the program
|
|
Using the command shell
|
|
Customizing the prompt
|
|
Keeping a log of your file transfers
|
|
Program options
|
|
A sample RC file
|
|
.De
|
|
.\"-------
|
|
.SH "Establishing the remote connection"
|
|
.\"-------
|
|
Just opening a connection to a remote server was inconvenient enough in the
|
|
stock
|
|
.I ftp
|
|
program to justify writing this program.
|
|
Here at
|
|
.IR NCEMRSoft ,
|
|
we want to do our business as quickly and painlessly as possible.
|
|
We'd
|
|
rather save time and wear and tear on our metacarpals than bother typing
|
|
entire site names, usernames, and email addresses masquerading as passwords,
|
|
and setting binary mode.
|
|
.PP
|
|
We made all connections anonymous by default, and we automatically send our
|
|
email address for the password on those connections.
|
|
We allowed for site
|
|
names to be abbreviated.
|
|
.PP
|
|
For each commonly accessed site, you can put an entry in your program
|
|
preferences file (let's call it the ``ncftprc file'' or ``RC file'' for short).
|
|
To open the site, from the command shell all you do is type:
|
|
.Ds
|
|
open wuarchive.wustl.edu
|
|
.De
|
|
.PP
|
|
or
|
|
.Ds
|
|
o wuarchive.wustl.edu
|
|
.De
|
|
.PP
|
|
As promised, you can abbreviate that further.
|
|
Just use any abbreviation that
|
|
would match only the site you had in mind.
|
|
For the previous example, you
|
|
could try:
|
|
.Ds
|
|
o wuarc
|
|
o wustl
|
|
o stl
|
|
o wu
|
|
.De
|
|
.PP
|
|
Any of those abbreviations would open wuarchive.wustl.edu anonymously,
|
|
sending your anon-password (usually set to your email address) as the
|
|
password.
|
|
Keep in mind that the program tries opening the first site
|
|
that matches the abbreviation you supplied.
|
|
So:
|
|
.Ds
|
|
o w
|
|
.De
|
|
.PP
|
|
might match a site named bowser.nintendo.co.jp if that site appeared before
|
|
your entry for wuarchive.wustl.edu.
|
|
.PP
|
|
Most of the time we open remote sites anonymously, but
|
|
there are times where you need to specifically open a site with an actual
|
|
username and password.
|
|
Let's say my partner, Phil Dietz, wants to FTP
|
|
something out of my account.
|
|
Perhaps he wants to fetch the latest version
|
|
of the source code to
|
|
.I NcFTP
|
|
so he can optimize something or add a new feature behind my back.
|
|
Since the
|
|
program opens remote sites anonymously by default (actually, you can change
|
|
this behavior; more on that later), he would have to specify a flag to the
|
|
.I open
|
|
command so he can supply my username and password.
|
|
He would try:
|
|
.Ds
|
|
o \-u sphygmomanometer.unl.edu
|
|
.De
|
|
.PP
|
|
or, more likely:
|
|
.Ds
|
|
o \-u sph
|
|
.De
|
|
.PP
|
|
Then the program would prompt him for a username (login, whatever) and a
|
|
password:
|
|
.Ds
|
|
Login Name (pdietz): mgleason
|
|
Password: ********
|
|
.De
|
|
.PP
|
|
If he got it right, he could raid my stuff.
|
|
If not, he'd probably drop
|
|
me an email asking me to quit changing my password so often.
|
|
.PP
|
|
There are even times where you want to FTP from your own account, like if
|
|
you are debugging an FTP client you wrote.
|
|
At this prompt:
|
|
.Ds
|
|
Login Name (mgleason):
|
|
.De
|
|
.PP
|
|
I could just hit return to tell the program that I want ``mgleason'' as my
|
|
username, then I would enter my password.
|
|
.\"-------
|
|
.SH "Format of the RC file"
|
|
.\"-------
|
|
This release of the program is somewhat compatible with the stock
|
|
.I ftp
|
|
program's
|
|
.B ".netrc"
|
|
file.
|
|
However, I can promise you that in the near future the program will
|
|
use a new format, so don't invest too much time in it.
|
|
.PP
|
|
The RC file can be named
|
|
.RB `` ncftprc '',
|
|
.RB `` netrc '',
|
|
or
|
|
.RB `` .ncftprc '',
|
|
but it is usually named
|
|
.RB `` .netrc ''
|
|
so it can be used with the stock
|
|
.I ftp
|
|
program.
|
|
.I NcFTP
|
|
looks in the current working directory for any of those files, and then in
|
|
your home directory, and after that it gives up (which is OK, because RC
|
|
files aren't mandatory).
|
|
.PP
|
|
The file usually starts with
|
|
.I #set
|
|
and
|
|
.I #unset
|
|
commands that do things
|
|
to the programs variables.
|
|
The reason for the ``#'' is so the stock
|
|
.I ftp
|
|
program will think they are comments.
|
|
You might have this appearing as
|
|
the first few lines in your RC file (I'll explain later):
|
|
.Ds
|
|
#set debug 1
|
|
#set pager "less \-EMi"
|
|
#unset startup\-msg
|
|
.De
|
|
.PP
|
|
After those, you put in machine entries for each of your favorite sites.
|
|
Let's put in an entry for wuarchive.wustl.edu.
|
|
First you would put:
|
|
.Ds
|
|
machine wuarchive.wustl.edu
|
|
.De
|
|
.PP
|
|
Then you could put in your username, password, and account if you like:
|
|
.Ds
|
|
user anonymous
|
|
password \-mgleason@cse.unl.edu
|
|
account wuarc.does.not.use.accounts
|
|
.De
|
|
.PP
|
|
Following that, you would add the startup macro that is run
|
|
each time you connect to wuarchive.
|
|
You must start it with this line:
|
|
.Ds
|
|
macdef init
|
|
.De
|
|
.PP
|
|
Then put in the commands you want to do:
|
|
.Ds
|
|
cd /graphics/gif
|
|
ls \-lt
|
|
.De
|
|
.PP
|
|
After that, you end the macro with a blank line (important!).
|
|
The finished machine entry would look like the following.
|
|
To make the transition to the impending new format less painful,
|
|
I recommend you adhere to this format:
|
|
.ta 6m +6m
|
|
.Ds
|
|
machine wuarchive.wustl.edu
|
|
user anonymous
|
|
password \-mgleason@cse.unl.edu
|
|
account wuarc.does.not.use.accounts
|
|
macdef init
|
|
cd /graphics/gif
|
|
ls \-lt
|
|
.RI \t( "mandatory blank line to end the macro" )
|
|
.De
|
|
.PP
|
|
Of course, if all you want to do is open wuarchive anonymously, you
|
|
needn't bother with the ``user'', ``password'', and ``account'' lines.
|
|
You may want to put them in if you plan on using the stock
|
|
.I ftp
|
|
program, though.
|
|
Try something like this:
|
|
.ta 6m +6m
|
|
.Ds
|
|
machine wuarchive.wustl.edu
|
|
macdef init
|
|
cd /graphics/gif
|
|
ls \-lt
|
|
.RI \t( "mandatory blank line to end the macro" )
|
|
.De
|
|
.PP
|
|
You can tell the program to not run the startup macro if you supply
|
|
.B "\-i"
|
|
to the
|
|
.I open
|
|
command.
|
|
.PP
|
|
Really, you should only bother adding entries for sites that you want to
|
|
run startup macros upon connection.
|
|
The next section explains why.
|
|
.\"-------
|
|
.SH "The Recent-sites file"
|
|
.\"-------
|
|
Each time you open a site, the program saves the name of the site and the
|
|
last directory you were in to the
|
|
.I recent-sites file
|
|
which is named
|
|
.B ".ncrecent"
|
|
and placed in your home directory.
|
|
The program saves a
|
|
predetermined number of these sites in the file, and when it reaches the
|
|
limit, it discards the oldest entry so it can add a new one.
|
|
.PP
|
|
You can just go ahead and use the name of the site you want with the
|
|
.I open
|
|
command if you know it is in the
|
|
.I recent\-file
|
|
(and you can abbreviate the
|
|
name, just like those in the RC file).
|
|
But if you cannot remember what the
|
|
name of the site you want, all you do is run the
|
|
.I open
|
|
command with
|
|
no site parameter:
|
|
.Ds
|
|
open
|
|
.De
|
|
.PP
|
|
This will pop up a list of the sites in the
|
|
.IR "recent-file" ,
|
|
and sites in your RC file.
|
|
At the open prompt, just type the name (or an
|
|
abbreviation of that name) or the number preceding the site name to open
|
|
that site.
|
|
After opening the site you wanted, the program sets the remote
|
|
working directory to the same one you left in the last time you called.
|
|
.PP
|
|
If you don't like the idea of having the sites you called stored on disk,
|
|
you can turn this feature off using an
|
|
.I unset
|
|
command, explained later.
|
|
.\"-------
|
|
.SH "Redialing a busy remote site"
|
|
.\"-------
|
|
Some remote sites limit the number of leeches, er, anonymous connections
|
|
at a time to reduce the load on the host computer.
|
|
You can use the
|
|
.I open
|
|
command's redial feature to keep attempting connections until you get on,
|
|
although that is not a very polite thing to do.
|
|
The simplest way to do
|
|
this would be to just supply the
|
|
.B \-r
|
|
option:
|
|
.Ds
|
|
open \-r wuarc
|
|
.De
|
|
.PP
|
|
There are also options you can use to tweak redial.
|
|
The
|
|
.B \-d
|
|
flag sets
|
|
the delay between dials, and the
|
|
.B \-g
|
|
flag sets a limit on how many dials
|
|
should be attempting before giving up.
|
|
If you don't supply
|
|
.B \-g
|
|
the program will dial a day and forever (which my Number Theory professor,
|
|
Dr. Mientka, says is longer than forever and a day)
|
|
until it connects successfully, or until you get sick of waiting and hit the
|
|
interrupt key (usually ^C).
|
|
.PP
|
|
This example dials wuarchive every ten minutes, giving up after twenty
|
|
attempts.
|
|
Note that the redial delay is specified in seconds:
|
|
.Ds
|
|
open \-r \-d 600 \-g 20 wuarc
|
|
.De
|
|
.PP
|
|
Please be considerate when you use redialing, so you won't tax the network.
|
|
Site administrators can and do get angry when they get flooded with
|
|
connections.
|
|
.\"-------
|
|
.SH "Supplying a sitename from your shell's command line"
|
|
.\"-------
|
|
When you run the program:
|
|
.Ds
|
|
ncftp
|
|
.De
|
|
.PP
|
|
by itself does nothing and waits for you to type commands to the program's
|
|
own shell.
|
|
Just like the stock
|
|
.I ftp
|
|
program, you can supply a site name
|
|
on the command line:
|
|
.Ds
|
|
ncftp wuarchive.wustl.edu
|
|
.De
|
|
.PP
|
|
You can also use abbreviations as usual:
|
|
.Ds
|
|
ncftp wuarc
|
|
.De
|
|
.PP
|
|
This is equivalent to running the program, then issuing an
|
|
.I open
|
|
command to open wuarchive.
|
|
.\"-------
|
|
.SH "Using Colon-mode"
|
|
.\"-------
|
|
The
|
|
.I open
|
|
command is not a one-trick pony.
|
|
Another option is what I call
|
|
.IR "colon-mode" .
|
|
This feature is used (most of the time) from your shell's
|
|
command line.
|
|
.PP
|
|
In ancient times, way back during the Disco era, you could use a program
|
|
called
|
|
.I tftp
|
|
to fetch a file using the Internet standard
|
|
.I Trivial File Transfer Protocol.
|
|
You could use that program to do something like this
|
|
from within its shell:
|
|
.Ds
|
|
get wuarchive.wustl.edu:/graphics/gif/README
|
|
.De
|
|
.PP
|
|
and that would call wuarchive and fetch the
|
|
.B README
|
|
file.
|
|
.PP
|
|
You can use this program to do the same thing from your shell's command
|
|
line:
|
|
.Ds
|
|
csh> ncftp wuarchive.wustl.edu:/graphics/gif/README
|
|
csh> head README
|
|
.De
|
|
.PP
|
|
This tells your shell, in this case the ``c-shell'' to run
|
|
.IR NcFTP ,
|
|
which
|
|
would open wuarchive, fetch
|
|
.B /graphics/gif/README
|
|
and write the file
|
|
.B ./README
|
|
in the current working directory, and then exits.
|
|
This is nice if you don't
|
|
want to browse around the remote site, and you know exactly want you want.
|
|
It would also come in handy in shell scripts, where you don't want to
|
|
enter the command shell, and might not want the program to spew output.
|
|
.PP
|
|
You can use
|
|
.I colon-mode
|
|
to set the starting remote working directory also:
|
|
.Ds
|
|
csh> ncftp wuarchive.wustl.edu:/graphics/gif
|
|
.De
|
|
.PP
|
|
This would run the program, open wuarchive, and
|
|
.I cd
|
|
to the gif directory, then run the program's command shell so you can
|
|
browse.
|
|
.PP
|
|
.I Colon-mode
|
|
is also available from within the program's command shell.
|
|
At a prompt you can do stuff like this:
|
|
.Ds
|
|
ncftp> open wuarchive.wustl.edu:/graphics/gif/README
|
|
ncftp> o wuarc:/graphics/gif
|
|
.De
|
|
.\"-------
|
|
.SH "Using FTP-cat and FTP-more mode"
|
|
.\"-------
|
|
There are times where you might not want the program to write a
|
|
.I colon-mode
|
|
file in the current working directory, or perhaps you want to pipe the
|
|
output of a remote file into something else.
|
|
.I Colon-mode
|
|
has options to
|
|
do this.
|
|
It was inspired by the guy who wrote the
|
|
.I ftpcat
|
|
perl script.
|
|
The
|
|
.B \-c
|
|
option tells the program to write on the standard
|
|
output stream.
|
|
The
|
|
.B \-m
|
|
option pipes the file into your pager (like
|
|
.IR more ")"
|
|
Of course this won't work if the thing you give
|
|
.I colon-mode
|
|
is a directory! This example just dumps a remote file to stdout:
|
|
.Ds
|
|
csh> ncftp \-c wuarc:/graphics/gif/README
|
|
\&...
|
|
csh>
|
|
.De
|
|
.PP
|
|
This example redirects a remote file into a different
|
|
location:
|
|
.Ds
|
|
csh> ncftp \-c wu:/README > ~pdietz/thesis.tex
|
|
.De
|
|
.PP
|
|
This one shows how to use a pipeline:
|
|
.Ds
|
|
csh> ncftp \-c wuarc:/README | tail | wc \-l
|
|
10
|
|
csh>
|
|
.De
|
|
.PP
|
|
This shows how to page a remote file:
|
|
.Ds
|
|
csh> ncftp \-m wuarc:/graphics/gif/README
|
|
\&...
|
|
csh>
|
|
.De
|
|
.\"-------
|
|
.SH "Supplying a port number with the open command"
|
|
.\"-------
|
|
This option just didn't fit anywhere else, so to finish out the open command,
|
|
.B \-p
|
|
lets you supply a port number if you have to
|
|
.I ftp
|
|
to a site using an nonstandard port number.
|
|
Personally, I have yet to use this feature, but it is
|
|
there for compatibility with the stock
|
|
.I ftp
|
|
program.
|
|
.\"-------
|
|
.SH "Displaying and changing program variables"
|
|
.\"-------
|
|
Now I'll explain the commands unique to
|
|
.IR NcFTP .
|
|
The others should perform the
|
|
same as they would in the stock
|
|
.I ftp
|
|
program;
|
|
consult the man page for it if you want those explained,
|
|
or use the
|
|
.I help
|
|
command for a brief blurb.
|
|
.PP
|
|
The
|
|
.I show
|
|
command is used to display program variables and their values.
|
|
.Ds
|
|
show all
|
|
.De
|
|
.PP
|
|
or
|
|
.Ds
|
|
show
|
|
.De
|
|
.PP
|
|
would display all the variables with their values.
|
|
.Ds
|
|
.RI show " var1 var2 ... varN"
|
|
.De
|
|
.PP
|
|
would display each specified variable and its value.
|
|
.PP
|
|
The
|
|
.I set
|
|
command changes the value of a program variable.
|
|
Its syntax is:
|
|
.Ds
|
|
.RI set " varname value"
|
|
.De
|
|
.PP
|
|
For Boolean or Integer variables,
|
|
.Ds
|
|
.RI set " varname"
|
|
.De
|
|
.PP
|
|
would set the value of the variable
|
|
.I varname
|
|
to
|
|
.B 1
|
|
.RB ( true ).
|
|
.PP
|
|
The
|
|
.I unset
|
|
command can be used to set the variable to its default value,
|
|
or for Boolean and Integer variables, set the value of the variable to
|
|
.B 0
|
|
.RB ( false ).
|
|
For String variables, you can use this to set the value to an
|
|
empty string.
|
|
.PP
|
|
You can use any of those three commands in both the command shell,
|
|
or in the RC file with a ``#'' prepended.
|
|
.\"-------
|
|
.SH "Program variables"
|
|
.\"-------
|
|
Each variable can be one of the following types:
|
|
.TP
|
|
Boolean:
|
|
Can be
|
|
.RB `` on ''
|
|
or
|
|
.RB `` off ''
|
|
(you can also use
|
|
.RB `` 1 ''
|
|
or
|
|
.RB `` 0 '').
|
|
.TP
|
|
Integer:
|
|
Can be any positive or negative number, or
|
|
.BR 0 .
|
|
.TP
|
|
String:
|
|
Is a string of characters.
|
|
If the string needs to have a space
|
|
in it, make sure you surround the whole string with double quotes in a
|
|
.I set
|
|
command.
|
|
.PP
|
|
Variables follow.
|
|
Some variables are explained later in the relevant sections.
|
|
.TP
|
|
.IR anon\-open " (Boolean)"
|
|
Tells whether the default login mode is anonymous if
|
|
on, or if off, will prompt for a username/password.
|
|
You can always override this by using either
|
|
.B \-a
|
|
or
|
|
.B \-u
|
|
with the
|
|
.I open
|
|
command.
|
|
.TP
|
|
.IR anon\-password " (String)"
|
|
Sends this as the password when you login anonymously.
|
|
By default this is your email address.
|
|
.TP
|
|
.IR ansi\-escapes " (Boolean)"
|
|
If on, the program can use boldface, underline,
|
|
and inverse text.
|
|
.TP
|
|
.IR auto\-binary " (Boolean)"
|
|
If on, sets the transfer type to binary mode
|
|
immediately after connection.
|
|
.TP
|
|
.IR debug " (Integer)"
|
|
Sets the debugging level.
|
|
.TP
|
|
.IR gateway\-login " (String)"
|
|
Tells which username to use when logging in to
|
|
your firewall gateway host.
|
|
.TP
|
|
.IR gateway\-host " (String)"
|
|
The site which is acting as your firewall gateway,
|
|
or empty if you aren't using one.
|
|
.TP
|
|
.IR local\-dir " (String)"
|
|
The current local working directory.
|
|
I like to set this from my RC file,
|
|
so all my files go into my download directory.
|
|
.TP
|
|
.IR logfile " (String)"
|
|
The name of your personal transfer log, or empty
|
|
if you aren't using a transfer log.
|
|
.TP
|
|
.IR logsize " (Integer)"
|
|
The maximum ceiling of your log file, before the program
|
|
removes old entries.
|
|
.TP
|
|
.IR mprompt " (Boolean)"
|
|
If on, prompts for each remote file expanded from a
|
|
wildcard globbing expression.
|
|
.TP
|
|
.IR netrc " (String, Read-only)"
|
|
Tells you the name of the RC file in use.
|
|
.TP
|
|
.IR pager " (String)"
|
|
The pathname and flags of the program used to display
|
|
output one screenful at a time.
|
|
The default is the value of your $PAGER
|
|
environment variable.
|
|
.TP
|
|
.IR prompt " (String)"
|
|
The prompt specification that expands into the prompt.
|
|
.TP
|
|
.IR progress\-reports " (Integer)"
|
|
Which progress meter to use, or
|
|
.B 0
|
|
if you don't want progress reports during file transfers.
|
|
Set it to
|
|
.B 1
|
|
for a simple percentage meter;
|
|
.B 2
|
|
for a fancy bar graph indicator;
|
|
.B 3
|
|
to print just the number of kilobytes transferred; or
|
|
.B 4
|
|
to print one dot for each 10% transferred, if you
|
|
want to avoid the use of backspaces. Note that the program
|
|
may use a different meter depending on how cooperative the
|
|
remote host is, and what you have the
|
|
.I ansi\-escapes
|
|
variable set to.
|
|
.TP
|
|
.IR recent\-list " (Boolean)"
|
|
If on, uses and updates the
|
|
.I recent\-file.
|
|
.TP
|
|
.IR remote\-is\-unix " (Boolean)"
|
|
Set automatically by the program upon connection,
|
|
you may need to use this in a startup macro if the program guessed
|
|
that a remote site was UNIX when it really is not.
|
|
.TP
|
|
.IR startup\-msg " (Boolean)"
|
|
If on, prints the opening message and tip.
|
|
.TP
|
|
.IR tips " (Boolean)"
|
|
If on, prints a tip on how to use the program better each
|
|
time you run the program.
|
|
.TP
|
|
.IR type " (String)"
|
|
The name of the file transfer mode in use,
|
|
such as
|
|
.RB `` binary ''
|
|
or
|
|
.RB `` ascii ''.
|
|
.TP
|
|
.IR verbose " (String/Integer)"
|
|
Controls the amount of output spewed by the program.
|
|
You can supply either the first character of the name of the
|
|
verbosity level, or its number:
|
|
.RS
|
|
.TP
|
|
.IR "Q" "uiet (\-1)"
|
|
Won't print any output at all, even if an error occurs.
|
|
.TP
|
|
.IR "E" "rrors Only (0)"
|
|
No output, except when errors occur.
|
|
.TP
|
|
.IR "T" "erse (1)"
|
|
Prints errors, and useful output from the remote host.
|
|
.TP
|
|
.IR "V" "erbose (2)"
|
|
Prints everything, even junk output from the remote end.
|
|
.RE
|
|
.\"-------
|
|
.SH "Listing a remote directory"
|
|
.\"-------
|
|
The
|
|
.I ls
|
|
and
|
|
.I dir
|
|
commands perform in a similar manner to those of the
|
|
stock
|
|
.I ftp
|
|
program.
|
|
.PP
|
|
The
|
|
.I ls
|
|
command sends the FTP command ``NLST'' for you.
|
|
This command has been set so that it defaults
|
|
to always listing files in columns (this is the
|
|
.B \-C
|
|
option given to the UNIX
|
|
.I ls
|
|
command) and appending
|
|
metacharacters to each item name (this is the
|
|
.B \-F
|
|
option), so you can
|
|
see which items are directories, files, links, etcetera.
|
|
If you don't want
|
|
your items columnized, you can try using the
|
|
.B \-1
|
|
option with
|
|
.I ls
|
|
to print one item per line.
|
|
.PP
|
|
The
|
|
.I dir
|
|
command sends the FTP command ``LIST'' for you, which instead
|
|
of printing just item names, it prints item sizes, owners, dates, and
|
|
permissions as well.
|
|
This command is equivalent to
|
|
.RB `` "ls \-l" ''
|
|
on most remote systems.
|
|
.PP
|
|
The usage for both commands is the same.
|
|
Here is the one for
|
|
.IR ls :
|
|
.PP
|
|
.RS
|
|
.B ls
|
|
.RI [ \-flags ]
|
|
.RI [ "directory and file names" ]
|
|
.RI [ redirection ]
|
|
.RE
|
|
.PP
|
|
Note that in this program, you can supply both flags and items to list in
|
|
the same command.
|
|
The stock version of
|
|
.I ftp
|
|
doesn't let you do this:
|
|
.Ds
|
|
ls \-lrt /info\-mac/help
|
|
.De
|
|
.PP
|
|
Another thing that the program does which the others should have done is
|
|
let you supply more than one item:
|
|
.Ds
|
|
ls \-lrt /info\-mac/help /pub /info\-mac/README
|
|
.De
|
|
.PP
|
|
You can also redirect the output into a file, or pipe it into something.
|
|
This example shows how to list the contents of the current remote directory,
|
|
and save the output into a file in the current local directory:
|
|
.Ds
|
|
ls \-t >ls.out
|
|
.De
|
|
.PP
|
|
Note that for this to work, there must be no whitespace between the ``>''
|
|
and the filename, unlike your shell command line which allows for extra
|
|
whitespace.
|
|
This will be (actually, is) fixed in a future version of the
|
|
program.
|
|
.PP
|
|
These examples show how to use a pipe:
|
|
.Ds
|
|
ls \-t |tail
|
|
dir \-t "|less \-CM"
|
|
ls \-t "|tail | wc"
|
|
.De
|
|
.PP
|
|
Like the redirection example, there must be no whitespace between the first
|
|
pipe character and the rest of the stuff.
|
|
The trick is that it has to
|
|
appear as one argument to the commands.
|
|
The second and third examples
|
|
illustrate the use of double quotes to squeeze extra parameters in.
|
|
The second example can be done without all that typing.
|
|
See the descriptions of the
|
|
.I pdir
|
|
and
|
|
.I pls
|
|
commands below.
|
|
.\"-------
|
|
.SH "Viewing a remote directory with your pager"
|
|
.\"-------
|
|
Didn't you hate it when you listed a remote directory, only to have most of
|
|
the stuff scrolled off your terminal before you could read it?
|
|
The
|
|
.I pls
|
|
and
|
|
.I pdir
|
|
commands take care of this for you.
|
|
As you might have guessed,
|
|
they perform exactly like their regular counterparts,
|
|
only you view them with your pager.
|
|
The pager to use is controlled by the
|
|
.I pager
|
|
program variable.
|
|
.\"-------
|
|
.SH "Redisplaying the last directory listing"
|
|
.\"-------
|
|
The program saves the listing into a local buffer,
|
|
so if you need to see it again (probably forgot about
|
|
.IR pdir )
|
|
you can use the
|
|
.I redir
|
|
and
|
|
.I predir
|
|
commands for this.
|
|
.\"-------
|
|
.SH "Fetching files from the remote host"
|
|
.\"-------
|
|
The
|
|
.I get
|
|
and
|
|
.I mget
|
|
retrieve remote files for you.
|
|
The usage for
|
|
.I get
|
|
is:
|
|
.Ds
|
|
get remote\-file [local\-file or redirection]
|
|
.De
|
|
.PP
|
|
To fetch
|
|
.B /pub/README
|
|
and write it as a file named
|
|
.BR ./junk/readme ,
|
|
try:
|
|
.Ds
|
|
get /pub/README ./junk/readme
|
|
.De
|
|
.PP
|
|
To fetch
|
|
.B /pub/README
|
|
and write it as
|
|
.BR ./README ,
|
|
just do:
|
|
.Ds
|
|
get /pub/README
|
|
.De
|
|
.PP
|
|
This lets you fetch a file using its whole pathname, and write a copy of
|
|
it in the current directory, without having to bother with typing a local
|
|
filename.
|
|
In the unlikely event that you have write permission to a
|
|
directory called
|
|
.B /pub
|
|
on your local machine, it would write
|
|
.RB `` README ''
|
|
in that directory.
|
|
.PP
|
|
Most of the time the file you want will be in the current remote directory,
|
|
so you can just do these:
|
|
.Ds
|
|
get README
|
|
get README ./junk/readme
|
|
.De
|
|
.PP
|
|
You can also use a redirection for
|
|
.IR get ,
|
|
just like you can with the
|
|
.IR ls ", " dir ", and " redir
|
|
commands.
|
|
As described earlier, you have
|
|
to conform to the format below for this release of the program:
|
|
.Ds
|
|
get README >/dev/null
|
|
get README |head
|
|
get README "|head \-8"
|
|
get README "|less \-EMi"
|
|
.De
|
|
.PP
|
|
The last example is facilitated by the
|
|
.I page
|
|
command described later.
|
|
.PP
|
|
The
|
|
.I get
|
|
command can also use a wildcard expression in an attempt to
|
|
match exactly one remote file.
|
|
I call it ``Poor Man's File Completion.''
|
|
If you've done a remote listing, and you decide you want to download a
|
|
file by the name of
|
|
.RB `` obnoxiouslylongpackagename.tar.Z '',
|
|
you can use
|
|
``PMFC'' to save some keystrokes.
|
|
Choose an expression that will only
|
|
match that one file, then use it with
|
|
.IR get :
|
|
.Ds
|
|
get obn*.Z a.tar.Z
|
|
.De
|
|
.PP
|
|
If your pattern was unique,
|
|
.I get
|
|
will fetch that file only.
|
|
If the pattern matched more than one file, the program will bitch and moan.
|
|
.PP
|
|
The
|
|
.I mget
|
|
command is used to fetch many files at a time.
|
|
The difference between
|
|
.I get
|
|
and
|
|
.I mget
|
|
is that
|
|
.I get
|
|
lets you write only one file,
|
|
but you can put it in a different directory, while
|
|
.I mget
|
|
fetches many files,
|
|
always writing them in the current local directory.
|
|
This example fetches several remote files at once:
|
|
.Ds
|
|
mget a.file.Z b.file.Z c.tar d.tar.Z
|
|
.De
|
|
.PP
|
|
The
|
|
.I mget
|
|
command, and its ugly sisters,
|
|
.I mput
|
|
and
|
|
.I mdelete
|
|
let you use wildcard expressions.
|
|
I could have done the previous example as:
|
|
.Ds
|
|
mget *.Z c.tar
|
|
.De
|
|
.PP
|
|
instead.
|
|
The ``m'' commands will verify each file,
|
|
if you have the program variable
|
|
.I mprompt
|
|
set.
|
|
.\"-------
|
|
.SH "Viewing a remote file with your pager"
|
|
.\"-------
|
|
If you would like to read a file on the remote host without saving a copy
|
|
of it on your machine, you can use the
|
|
.I page
|
|
(or
|
|
.I more
|
|
if you wish) command:
|
|
.Ds
|
|
page README
|
|
page obn*README
|
|
page README.Z
|
|
.De
|
|
.PP
|
|
The second example show that you can use ``PMFC'' like you can for
|
|
.IR get.
|
|
The third example will work also, because if the program knows how to
|
|
decompress the file, it will do so before feeding it to your pager.
|
|
As stated earlier,
|
|
you can change the program to use to page by setting the program variable
|
|
.IR pager.
|
|
.\"-------
|
|
.SH "Creating a message file on the remote host"
|
|
.\"-------
|
|
Use the
|
|
.I create
|
|
an empty file on the remote site.
|
|
Sometimes it is necessary to leave a note if you can't get in touch
|
|
with the remote site's administrator.
|
|
For example if a file is corrupted, you could try:
|
|
.Ds
|
|
create Foo.tar_is_corrupt
|
|
.De
|
|
.PP
|
|
in hopes that the original uploader will replace it.
|
|
.\"-------
|
|
.SH "Looking up site names and addresses"
|
|
.\"-------
|
|
You can use the program's builtin
|
|
.RI mini- nslookup
|
|
facility.
|
|
If you wanted to know the site's IP number, but only knew the name you
|
|
could do:
|
|
.Ds
|
|
lookup cse.unl.edu
|
|
.De
|
|
.PP
|
|
This would spit out IP number for that site, in this case ``129.93.1.12''.
|
|
If you needed to know what a site's name was, but only knew the IP number,
|
|
try:
|
|
.Ds
|
|
lookup 129.93.1.12
|
|
.De
|
|
.PP
|
|
This would spit out the name for that site, in this case ``cse.unl.edu''.
|
|
.\"-------
|
|
.SH "Checking the configuration of the program"
|
|
.\"-------
|
|
Use the
|
|
.I version
|
|
command to print version and compilation information about the program.
|
|
This will also tell you which optional features are
|
|
compiled into the program, such as logging to the system log and which
|
|
command line editor (if any) has been installed.
|
|
.PP
|
|
The author's email address is listed, and if you need to report something,
|
|
send the output of this command along with your message.
|
|
.\"-------
|
|
.SH "Using the command shell"
|
|
.\"-------
|
|
Just like the stock
|
|
.I ftp
|
|
program, you type commands to it until you get
|
|
bored and hit either ^D or type the
|
|
.I quit
|
|
command.
|
|
.PP
|
|
The program supports links to popular command line editing libraries.
|
|
If the person who compiled it went to the effort, you will be able to
|
|
edit the command line with arrow keys and other editing commands, and also
|
|
scroll up and down in the command line history, usually with the up and
|
|
down arrows.
|
|
You can check the
|
|
.I version
|
|
command to see if either
|
|
``GETLINE'' or ``READLINE'' are installed.
|
|
.\"-------
|
|
.SH "Customizing the prompt"
|
|
.\"-------
|
|
You can set the shell's prompt string to whatever you like.
|
|
You can use several metacharacters that expand into something each prompt.
|
|
The
|
|
.RB `` % ''
|
|
flags are passed to
|
|
.IR strftime (3),
|
|
so you can put the date or time in the prompt formatted as you like it:
|
|
.Ds
|
|
set prompt "%I:%M ncftp>"
|
|
.De
|
|
.PP
|
|
That would insert the current time in the prompt.
|
|
.PP
|
|
The
|
|
.RB `` @ ''
|
|
flags are expanded by the program itself.
|
|
Here's the list of them.
|
|
.PP
|
|
If you have an ANSI-compatible terminal, or you have the program variable
|
|
.I ansi\-escapes
|
|
set, you can use
|
|
.BR @B ,
|
|
.BR @I ,
|
|
and
|
|
.B @U
|
|
to turn on boldface,
|
|
inverse, and underline text respectively (otherwise they won't insert
|
|
anything).
|
|
You can also use
|
|
.B @R
|
|
to turn on inverse (reverse) text.
|
|
.B @P
|
|
sets the text back to plain text.
|
|
.PP
|
|
.B @D
|
|
Inserts the full path of the current remote directory.
|
|
The
|
|
.B @J
|
|
flag is similar except it inserts only the directory name.
|
|
.PP
|
|
.B @H
|
|
Inserts the name of the remote host.
|
|
.B @C
|
|
inserts the host and current
|
|
directory path in
|
|
.I "colon-mode"
|
|
format, such as
|
|
``cse.unl.edu:/pub/mgleason'', or ``(not connected)''.
|
|
The
|
|
.B @c
|
|
flag is similar, only it will insert ``cse.unl.edu:/pub/mgleason'' and a
|
|
newline if connected, otherwise it prints nothing.
|
|
The default prompt uses
|
|
this flag to print a two line prompt when connected and a one line prompt
|
|
when not connected.
|
|
.PP
|
|
.BR @E " or " @!
|
|
inserts the event number (how many commands you've typed).
|
|
.PP
|
|
.B @M
|
|
inserts ``(Mail)\0'' if mail has arrived since running the program.
|
|
.PP
|
|
.B @N
|
|
inserts a newline character.
|
|
.\"-------
|
|
.SH "Keeping a log of your file transfers"
|
|
.\"-------
|
|
You can have the program keep a personal log file.
|
|
I find it is useful so I can see where I got a certain file,
|
|
or what the name of that site was I called two weeks ago.
|
|
.PP
|
|
To use a log, add:
|
|
.Ds
|
|
#set logfile ~/.ftplog
|
|
.De
|
|
.PP
|
|
(or whatever you want to name the log) to your RC file.
|
|
I don't want my log growing too large and using up all my disk space,
|
|
so I also have:
|
|
.Ds
|
|
#set logsize 10240
|
|
.De
|
|
.PP
|
|
in my RC file.
|
|
If you set the limit on the maximum log size, the program will
|
|
keep the log file at or below that size, discarding old entries.
|
|
.PP
|
|
Note that this is different from having SYSLOG appear in the
|
|
.I version
|
|
command's output.
|
|
When this is on, your actions are recorded to the system
|
|
log, so your system administrator can make sure you aren't doing anything
|
|
``bad.''
|
|
.\"-------
|
|
.SH "Program options"
|
|
.\"-------
|
|
Remember that you can treat the command line like an
|
|
.I open
|
|
command,
|
|
so all lowercase options are passed to the
|
|
.I open
|
|
command, and the
|
|
uppercase options are handled by the main program.
|
|
The uppercase options
|
|
are described below; refer to the
|
|
.I open
|
|
command for descriptions of its options.
|
|
.TP
|
|
.BI \-D " x"
|
|
sets the debugging level to
|
|
.IR x .
|
|
.TP
|
|
.B \-H
|
|
runs the
|
|
.I version
|
|
command and exits, so you can save the output of
|
|
it to use when you need to mail me something.
|
|
.TP
|
|
.B \-I
|
|
toggles the mprompt variable; this is provided for compatibility with
|
|
.RB `` "ftp \-i" ''.
|
|
.TP
|
|
.B \-N
|
|
disables reading of the RC file;
|
|
this is provided for compatibility with
|
|
.RB `` "ftp \-n" ''.
|
|
.TP
|
|
.B \-P
|
|
toggle passive mode (defaults to on). Useful for work behind firewalls.
|
|
.TP
|
|
.BI \-V " x"
|
|
sets verbosity to level
|
|
.I x
|
|
.RB ( \-1 ,
|
|
.BR 0 ,
|
|
.BR 1 ,
|
|
.BR 2 )
|
|
or
|
|
.RB ( quiet ,
|
|
.BR errs ,
|
|
.BR terse ,
|
|
.BR verbose ).
|
|
See the description of the
|
|
.I verbose
|
|
program variable for more information.
|
|
.PP
|
|
Here are some example command lines.
|
|
Again, see the description of the
|
|
.I open
|
|
command (especially
|
|
.IR "colon-mode" " and " "FTP\-cat mode" ")"
|
|
and all its functions for more information.
|
|
.PP
|
|
This just enters the
|
|
.I NcFTP
|
|
command shell:
|
|
.Ds
|
|
csh> ncftp
|
|
.De
|
|
.PP
|
|
This fetches
|
|
.B CONTENTS
|
|
and then quits:
|
|
.Ds
|
|
csh> ncftp cse.unl.edu:/pub/mgleason/CONTENTS
|
|
.De
|
|
.PP
|
|
Some others examples, with open options and main program options mixed in:
|
|
.Ds
|
|
csh> ncftp \-V quiet \-u ftp.unl.edu
|
|
csh> ncftp \-c cse.unl.edu:/pub/mgleason/CONTENTS
|
|
csh> ncftp \-D 2 \-r \-d 120 \-g 10 \-N ftp.unl.edu
|
|
.De
|
|
.\"-------
|
|
.SH "A sample RC file"
|
|
.\"-------
|
|
Here is a sample RC file:
|
|
.ta 6m +6m
|
|
.Ds
|
|
#set logfile ~/.ftplog
|
|
#set progress\-reports 2
|
|
#set local\-dir /usr/tmp/zz
|
|
#set prompt "@B@E @UNcFTP@P @B@M@D@P \->"
|
|
.sp
|
|
machine sumex\-aim.stanford.edu
|
|
macdef init
|
|
cd /info\-mac
|
|
get ./help/recent\-files.txt "|grep \-v '.abs' > sumex"
|
|
!less sumex
|
|
pwd
|
|
.sp
|
|
# This site is in here just so I can use ``apple''
|
|
# as an abbreviation.
|
|
machine ftp.apple.com
|
|
.sp
|
|
# NcFTP will only ask for your password:
|
|
machine cse.unl.edu
|
|
login mgleason
|
|
.sp
|
|
# You can supply a login and a password:
|
|
machine fake.machine.unl.edu
|
|
login mgleason
|
|
password mypass
|
|
macdef init
|
|
cd ./foo/bar
|
|
.sp
|
|
# If an antiquated non-UNIX machine doesn't use
|
|
# the "SYST" command, you may need to unset
|
|
# remote\-is\-unix, if the remote host complains
|
|
# about ``ls \-CF''.
|
|
machine some.vms.unl.edu
|
|
macdef init
|
|
unset remote\-is\-unix
|
|
.sp
|
|
.De
|
|
.\"-------
|
|
.SH "AUTHORS"
|
|
.\"-------
|
|
.I NcFTP
|
|
was written by Mike Gleason,
|
|
.I NCEMRSoft
|
|
(mgleason@cse.unl.edu), and based on code by the authors of the
|
|
.I ftp
|
|
from the BSD 4.3 distribution.
|
|
.I NcFTP
|
|
is copyrighted 1992, 1993 by NCEMRSoft
|
|
and 1985, 1989 by the Regents of California.
|
|
.PP
|
|
Ideas and some code contributed by Phil Dietz,
|
|
.I NCEMRSoft
|
|
(pdietz@cse.unl.edu).
|
|
Testing and debugging done by Phil and
|
|
Kok Hon Yin (hkok@cse.unl.edu).
|
|
.PP
|
|
Extensive man page formatting work
|
|
by DaviD W. Sanderson (dws@ssec.wisc.edu).
|
|
.\"-------
|
|
.SH "BUGS"
|
|
.\"-------
|
|
Correct execution of many commands depends upon proper behavior
|
|
by the remote server.
|
|
.PP
|
|
The remote server may drop the connection if you take a long time to
|
|
page remote files.
|
|
.PP
|
|
Termcap padding is not correctly displayed.
|
|
.PP
|
|
There are no such sites named
|
|
.I bowser.nintendo.co.jp
|
|
or
|
|
.IR sphygmomanometer.unl.edu .
|
|
.\"-------
|
|
.SH "SEE ALSO"
|
|
.\"-------
|
|
.IR strftime (3),
|
|
.IR ftpd (8),
|
|
.IR ftp (1),
|
|
.IR nslookup (8),
|
|
.IR compress (1),
|
|
.IR gzip (1),
|
|
.IR zcat (1),
|
|
.IR fsp (1),
|
|
.IR archie (1),
|
|
.IR tftp (1).
|