aboutsummaryrefslogtreecommitdiffstats
path: root/usr.bin/ncftp/ncftp.1
blob: 695bec0164d956e175ebcff3b5bb69fa055eb0d0 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
.\"-------
.\" 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 "1.9" 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@ftp.cs.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@ftp.cs.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 ftp.cs.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 ``ftp.cs.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
``ftp.cs.unl.edu:/pub/mgleason'', or ``(not connected)''.
The
.B @c
flag is similar, only it will insert ``ftp.cs.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 ftp.cs.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 ftp.cs.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 ftp.cs.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,
.IR NCEMRSoft "."
Testing and debugging done by Phil and
Kok Hon Yin
.PP
Extensive man page formatting work
by DaviD W. Sanderson (dws@ssec.wisc.edu).
.PP
As of this writing, the most recent version is archived in
/pub/ncftp, on
.IR "ftp.cs.unl.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).