Here is the list of section headers; I have my $MANPAGER environment variable set to use ``less -i'' so that I can skip to the section I want (otherwise, /regex commands to the pager won't match the section headers because of the formatting codes; the ``-i'' can search through the formatting codes)
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
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.
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:
open wuarchive.wustl.edu
or
o wuarchive.wustl.edu
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:
o wuarc o wustl o stl o wu
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:
o w
might match a site named bowser.nintendo.jp if that site appeared before your entry for wuarchive.wustl.edu.
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 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 open command so he can supply my username and password. He would try:
o -u sphygmomanometer.unl.edu
or, more likely:
o -u sph
Then the program would prompt him for a username (login, whatever) and a password:
Login Name (pdietz): mgleason Password: ********
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.
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:
Login Name (mgleason):
I could just hit return to tell the program that I want ``mgleason'' as my username, then I would enter my password.
The RC file can be named ``ncftprc'', ``netrc'', or ``.ncftprc'', but it is usually named ``.netrc'' so it can be used with the stock ftp program. 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).
The file usually starts with #set and #unset commands that do things to the programs variables. The reason for the ``#'' is so the stock 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):
#set debug 1 #set pager "less -EMi" #unset startup-msg
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:
machine wuarchive.wustl.edu
Then you could put in your username, password, and account if you like:
user anonymous password -mgleason@cse.unl.edu account wuarc.does.not.use.accounts
Following that, you would add the startup macro that is run each time you connect to wuarchive. You must start it with this line:
macdef init
Then put in the commands you want to do:
cd /graphics/gif ls -lt
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:
machine wuarchive.wustl.edu
user anonymous
password -mgleason@cse.unl.edu
account wuarc.does.not.use.accounts
macdef init
cd /graphics/gif
ls -lt
(mandatory blank line to end the macro)
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 ftp program, though. Try something like this:
machine wuarchive.wustl.edu
macdef init
cd /graphics/gif
ls -lt
(mandatory blank line to end the macro)
You can tell the program to not run the startup macro if you supply -i to the open command.
Really, you should only bother adding entries for sites that you want to run startup macros upon connection. The next section explains why.
You can just go ahead and use the name of the site you want with the open command if you know it is in the 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 open command with no site parameter:
open
This will pop up a list of the sites in the 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.
If you don't like the idea of having the sites you called stored on disk, you can turn this feature off using an unset command, explained later.
open -r wuarc
There are also options you can use to tweak redial. The -d flag sets the delay between dials, and the -g flag sets a limit on how many dials should be attempting before giving up. If you don't supply -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).
This example dials wuarchive every ten minutes, giving up after twenty attempts. Note that the redial delay is specified in seconds:
open -r -d 600 -g 20 wuarc
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.
ncftp
by itself does nothing and waits for you to type commands to the program's own shell. Just like the stock ftp program, you can supply a site name on the command line:
ncftp wuarchive.wustl.edu
You can also use abbreviations as usual:
ncftp wuarc
This is equivalent to running the program, then issuing an open command to open wuarchive.
In ancient times, way back during the Disco era, you could use a program called tftp to fetch a file using the Internet standard Trivial File Transfer Protocol. You could use that program to do something like this from within its shell:
get wuarchive.wustl.edu:/graphics/gif/README
and that would call wuarchive and fetch the README file.
You can use this program to do the same thing from your shell's command line:
csh> ncftp wuarchive.wustl.edu:/graphics/gif/README csh> head README
This tells your shell, in this case the ``c-shell'' to run NcFTP, which would open wuarchive, fetch /graphics/gif/README and write the file ./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.
You can use colon-mode to set the starting remote working directory also:
csh> ncftp wuarchive.wustl.edu:/graphics/gif
This would run the program, open wuarchive, and cd to the gif directory, then run the program's command shell so you can browse.
Colon-mode is also available from within the program's command shell. At a prompt you can do stuff like this:
ncftp> open wuarchive.wustl.edu:/graphics/gif/README ncftp> o wuarc:/graphics/gif
csh> ncftp -c wuarc:/graphics/gif/README ... csh>
This example redirects a remote file into a different location:
csh> ncftp -c wu:/README > ~pdietz/thesis.tex
This one shows how to use a pipeline:
csh> ncftp -c wuarc:/README | tail | wc -l 10 csh>
This shows how to page a remote file:
csh> ncftp -m wuarc:/graphics/gif/README ... csh>
The show command is used to display program variables and their values.
show all
or
show
would display all the variables with their values.
show var1 var2 ... varN
would display each specified variable and its value.
The set command changes the value of a program variable. Its syntax is:
set varname value
For Boolean or Integer variables,
set varname
would set the value of the variable varname to 1 (true).
The 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 0 (false). For String variables, you can use this to set the value to an empty string.
You can use any of those three commands in both the command shell, or in the RC file with a ``#'' prepended.
Variables follow. Some variables are explained later in the relevant sections.
The 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 -C option given to the UNIX ls command) and appending metacharacters to each item name (this is the -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 -1 option with ls to print one item per line.
The 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 ``ls -l'' on most remote systems.
The usage for both commands is the same. Here is the one for ls:
Note that in this program, you can supply both flags and items to list in the same command. The stock version of ftp doesn't let you do this:
ls -lrt /info-mac/help
Another thing that the program does which the others should have done is let you supply more than one item:
ls -lrt /info-mac/help /pub /info-mac/README
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:
ls -t >ls.out
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.
These examples show how to use a pipe:
ls -t |tail dir -t "|less -CM" ls -t "|tail | wc"
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 pdir and pls commands below.
get remote-file [local-file or redirection]
To fetch /pub/README and write it as a file named ./junk/readme, try:
get /pub/README ./junk/readme
To fetch /pub/README and write it as ./README, just do:
get /pub/README
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 /pub on your local machine, it would write ``README'' in that directory.
Most of the time the file you want will be in the current remote directory, so you can just do these:
get README get README ./junk/readme
You can also use a redirection for get, just like you can with the ls, dir, and redir commands. As described earlier, you have to conform to the format below for this release of the program:
get README >/dev/null get README |head get README "|head -8" get README "|less -EMi"
The last example is facilitated by the page command described later.
The 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 ``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 get:
get obn*.Z a.tar.Z
If your pattern was unique, get will fetch that file only. If the pattern matched more than one file, the program will bitch and moan.
The mget command is used to fetch many files at a time. The difference between get and mget is that get lets you write only one file, but you can put it in a different directory, while mget fetches many files, always writing them in the current local directory. This example fetches several remote files at once:
mget a.file.Z b.file.Z c.tar d.tar.Z
The mget command, and its ugly sisters, mput and mdelete let you use wildcard expressions. I could have done the previous example as:
mget *.Z c.tar
instead. The ``m'' commands will verify each file, if you have the program variable mprompt set.
page README page obn*README page README.Z
The second example show that you can use ``PMFC'' like you can for 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 pager.
create Foo.tar_is_corrupt
in hopes that the original uploader will replace it.
lookup cse.unl.edu
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:
lookup 129.93.1.12
This would spit out the name for that site, in this case ``cse.unl.edu''.
The author's email address is listed, and if you need to report something, send the output of this command along with your message.
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 version command to see if either ``GETLINE'' or ``READLINE'' are installed.
set prompt "%I:%M ncftp>"
That would the current time in the prompt.
The ``@'' flags are expanded by the program itself. Here's the list of them.
If you have an ANSI-compatible terminal, or you have the program variable ansi-escapes set, you can use @B, @I, and @U to turn on boldface, inverse, and underline text respectively (otherwise they won't insert anything). You can also use @R to turn on inverse (reverse) text. @P sets the text back to plain text.
@D Inserts the full path of the current remote directory. The @J flag is similar except it inserts only the directory name.
@H Inserts the name of the remote host. @C inserts the host and current directory path in colon-mode format, such as ``cse.unl.edu:/pub/mgleason'', or ``(not connected)''. The @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.
@E or @! inserts the event number (how many commands you've typed).
@M inserts ``(Mail) '' if mail has arrived since running the program.
@N inserts a newline character.
To use a log, add:
#set logfile ~/.ftplog
(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:
#set logsize 10240
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.
Note that this is different from having SYSLOG appear in the 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.''
Here are some example command lines. Again, see the description of the open command (especially colon-mode and FTP-cat mode) and all its functions for more information.
This just enters the NcFTP command shell:
csh> ncftp
This fetches CONTENTS and then quits:
csh> ncftp cse.unl.edu:/pub/mgleason/CONTENTS
Some others examples, with open options and main program options mixed in:
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
#set logfile ~/.ftplog
#set progress-reports 2
#set local-dir /usr/tmp/zz
#set prompt "@B@E @UNcFTP@P @B@M@D@P ->"
machine sumex-aim.stanford.edu
macdef init
cd /info-mac
get ./help/recent-files.txt "|grep -v '.abs' > sumex
!less sumex
pwd
# This site is in here just so I can use ``apple''
# as an abbreviation.
machine ftp.apple.com
# NcFTP will only ask for your password:
machine cse.unl.edu
login mgleason
# You can supply a login and a password:
machine fake.machine.unl.edu
login mgleason
password mypass
macdef init
cd ./foo/bar
# 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
Ideas and some code contributed by Phil Dietz, NCEMRSoft (pdietz@cse.unl.edu). Testing and debugging done by Phil and Kok Hon Yin (hkok@cse.unl.edu).
Extensive man page formatting work by DaviD W. Sanderson (dws@ssec.wisc.edu).
The remote server may drop the connection if you take a long time to page remote files.
Termcap padding is not correctly displayed.
There are no such sites named bowser.nintendo.jp or sphygmomanometer.unl.edu.