ncftp 1.8.5

1 files changed, 1393 insertions, 0 deletions

diff --git a/usr.bin/ncftp/ncftp.1 b/usr.bin/ncftp/ncftp.1
new file mode 100644
index 0000000..37cf474
--- /dev/null
+++ b/usr.bin/ncftp/ncftp.1
@@ -0,0 +1,1393 @@
+.\"-------
+.\" 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
+.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 (1),
+.IR compress (1),
+.IR gzip (1),
+.IR zcat (1),
+.IR fsp (1),
+.IR archie (1),
+.IR tftp (1).