File: efs.texi

package info (click to toggle)
xemacs21-packages 2009.02.17.dfsg.2-4
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 116,276 kB
  • ctags: 89,333
  • sloc: lisp: 1,232,060; ansic: 16,570; java: 13,514; xml: 6,477; sh: 4,617; makefile: 4,022; asm: 3,007; perl: 840; cpp: 500; ruby: 257; csh: 96; haskell: 93; awk: 49; python: 47
file content (1593 lines) | stat: -rw-r--r-- 62,455 bytes parent folder | download | duplicates (2)
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
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
\input texinfo   @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename efs.info
@settitle EFS
@comment %**end of header (This is for running Texinfo on a region.)

@direntry
* EFS::		Transparent remote file access via FTP.
@end direntry

@synindex fn vr

@node Top, What is EFS?, (dir), (dir)
@comment  node-name,  next,  previous,  up
@ifinfo
@unnumbered EFS

This file documents EFS, a system for transparent file-transfer
between remote hosts using the FTP protocol within Emacs.

This info is for version 1.24 of EFS.

Documentation version: 1.4

Copyright @copyright{} 1991, 1992 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
@end ifinfo

@titlepage
@sp 5
@center @titlefont{EFS}
@center version 1.20
@sp 2
@center A transparent remote file system, by Sandy Rutherford, Andy
Norman, and Mike Sperber
@sp 7
@center This documentation based on ange-ftp documentation by David Smith
@center and on documentation in the EFS source code
@center It was put together by Mike Sperber.

This documentation is preliminary.

@center Info Version 1.4
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1991, 1992 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
@end titlepage

@menu
* What is EFS?::                
* Installing EFS::              Where to find it, and how to use it.
* Using EFS::                   EFS -- a users' guide.
* Getting help::                Mailing lists and newsgroups.
* Bugs::                        Known bugs, and a wish list.

Indices:
* Concept Index::               
* Variable and function index::  
@end menu


@node What is EFS?, Installing EFS, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introducing EFS

EFS is a system for transparent file-transfer between remote VMS, CMS,
MTS, MVS, Twenex, Explorer (the last two are Lisp machines), TOPS-20,
DOS (running the Distinct, Novell, FTP software, NCSA, Microsoft in both
unix and DOS mode, Super TCP, and Hellsoft FTP servers), Windows NT
(running the Microsoft or Hummingbird ftp servers), Unix descriptive
listings (dl), KA9Q, OS/2 hosts using FTP. This means that you can edit,
copy and otherwise manipulate files on any machine you have access to
from within Emacs as if it were a local file. EFS works by introducing
an extended filename syntax, and overloading functions such as
@code{insert-file-contents} so that accessing a remote file causes
appropriate commands to be sent to an FTP process. EFS includes and
enhanced version of Dired to facilitate directory browsing and multiple
file transfer from remote hosts.

The authors of EFS are Sandy Rutherford (@code{sandy@@math.ubc.ca}),
Andy (Ange) Norman (@code{ange@@hplb.hpl.hp.com}), and
Mike Sperber (@code{sperber@@informatik.uni-tuebingen.de}).
EFS is partly based on an earlier package called ange-ftp.

@ifinfo
Many people have sent in enhancements for ange-ftp and EFS.
Members of the ange-ftp and EFS Hall of Fame include:

@itemize @bullet
@item
Many thanks to Roland McGrath for improving the filename syntax handling,
for suggesting many enhancements and for numerous cleanups to the code.

@item
Thanks to Jamie Zawinski for bugfixes and for ideas such as gateways.

@item
Thanks to Ken Laprade for improved @file{.netrc} parsing and password
reading, and Dired/shell autoloading.

@item
Thanks to Sebastian Kremer for tree dired support and for many ideas and
bugfixes.

@item
Thanks to Joe Wells for bugfixes, non-UNIX system support, VOS support,
and hostname completion.

@item
Thanks to Nakagawa Takayuki for many good ideas, filename-completion, help
with file-name expansion, efficiency worries, stylistic concerns and many
bugfixes.

@item
Also, thanks to Rob Austein, Doug Bagley, Andy Caiger, Jim Franklin,
Noah Friedman, Aksnes Knut-Havard, Elmar Heeb, John Interrante, Roland
McGrath, Jeff Morgenthaler, Mike Northam, Jens Petersen, Jack Repenning,
Joerg-Martin Schwarz, Michael Sperber, Svein Tjemsland, Andy Whitcroft,
Raymond A. Wiker and many others whose names have been forgotten who
have helped to debug and fix problems.
@end itemize
@end ifinfo

Finally, this info file was put together by Mike Sperber
(@code{sperber@@informatik.uni-tuebingen.de}) from an ange-ftp info file
written by Dave Smith (@code{dsmith@@stats.adelaide.edu.au}) and the EFS
source code.

@node Installing EFS, Using EFS, What is EFS?, Top
@comment  node-name,  next,  previous,  up
@chapter Installing EFS

There are a few customisations after installation you might need to
make. The ideal configuration is to have the FTP process running on the
same machine as you are running Emacs on, but this is not always
possible since some machines cannot access hosts outside the local
network. In this case, the FTP process needs to be run on a machine
which @emph{does} have access to the local world --- this is called the
@strong{gateway host}. EFS has facilities to make use of a gateway host
when accessing remote hosts.

@menu
* Obtaining source code::       Where to find the EFS source.
* Installing source::           Where to put it, how to load it.
* Customization::               How to tailor EFS to your needs.
* Using a gateway::             If your local machine has limited access.
* Setting up a gateway::        
* Gateway types::               
* Gateway problems::            
* EFS and archie.el::           
@end menu

@node Obtaining source code, Installing source, Installing EFS, Installing EFS
@comment  node-name,  next,  previous,  up
@section How to get the EFS source code

The latest separately distributed version of EFS should always be
available from Mike Sperber's home page at
@example
http://www-pu.informatik.uni-tuebingen.de/users/sperber/software/efs/
@end example

There are also some ftp locations:

@table @b
@item Switzerland
@example
/anonymous@@itp.ethz.ch:/sandy/efs/
@end example

@item Massachusetts, USA
@example
/anonymous@@alpha.gnu.ai.mit.edu:/efs/
@end example

@item California, USA
@example
/anonymous@@ftp.hmc.edu:/pub/emacs/packages/efs/
@end example
@end table

Failing these, someone on the EFS mailing list (see @xref{Getting help}.) may
be able to help you find the latest version.

@node Installing source, Customization, Obtaining source code, Installing EFS
@comment  node-name,  next,  previous,  up
@section Installing the source

For byte-compiling the EFS package, you should follow the instructions
at the top of the @file{INSTALL}.  If you have any problems, please let
us know so that we can fix them for other users. Don't even consider
using EFS without byte compiling it. It will be far too slow.

If you decide to byte compile efs by hand, it is important that the file
@file{efs-defun.el} be byte compiled first, followed by @file{efs.el}.
The other files may be byte compiled in any order.

To use EFS, simply put the byte compiled files in your load path
and add

@example
(require 'efs)
@end example

in your @file{.emacs} file.  Note this takes awhile, and some users have
found this to be unbearably slow.  Therefore ...

If you would like efs to be autoloaded when you attempt to access
a remote file, put

@example
(require 'efs-auto)
@end example

in your @file{.emacs} file. Note that there are some limitations associated
with autoloading EFS. A discussion of them is given at the top of
@file{efs-auto.el}.

Note that, in XEmacs, EFS automatically loads @file{efs-auto} when the
user accesses a remote file.  Therefore, no additional @code{require}
statements should be necessary to use EFS.  Just fire away ...

The above instructions should allow you to access all hosts that your
local machine can access. If your local host has limited access,
however, you may wish to have EFS working through a gateway
machine. If so, read on. Otherwise, to get started
using EFS, see @xref{Using EFS}.

@node Customization, Using a gateway, Installing source, Installing EFS
@comment  node-name,  next,  previous,  up
@section Customizing EFS

There are many customization options for EFS, and only a few of them
need to be touched in any specific setup.  All options are available
through the Custom package, see @xref{(Custom)Top}.  EFS provides access
through the customization group @code{efs}.


@node Using a gateway, Setting up a gateway, Customization, Installing EFS
@comment  node-name,  next,  previous,  up
@section Using a gateway

Sometimes it is necessary for the FTP process to be run on a different
machine than the machine running Emacs.  This can happen when the
local machine has restrictions on what hosts it can access.

Suppose you are running Emacs (and EFS, of course) on a machine X
(let's call it the `local host') and you want to access a file on a
machine Z (which we will call the `remote host'). Unfortunately, X does
not have FTP access to Z: when you try a manual FTP something like
the following happens:
@example
X$ ftp Z.foo.bar.com
ftp: connect: Host is unreachable
@end example
@noindent
However, X @emph{does} have access to a machine Y (the `gateway
machine') which @emph{can} access Z. Fortunately, you have an account on
the gateway machine, and so the solution is to login to Y, ftp to Z,
download the file you want from Z to Y, and then copy it from Y to the
local host, X. This can get a bit tedious, to say the least, but
fortunately EFS can do all the hard work for you.

@node Setting up a gateway, Gateway types, Using a gateway, Installing EFS
@comment  node-name,  next,  previous,  up
@section Setting up a gateway

@enumerate

@item
Set the variable @code{efs-gateway-host} to the name of your ftp gateway
machine
@vindex efs-gateway-host
if your net world is divided into two domains according to
@code{efs-local-ftp-host-regexp}.  If you need to use a nonstandard port
to access this host for gateway use, then specify
@code{efs-gateway-host} as @code{<hostname>#<port>}.

@item
Set the variable @code{efs-ftp-local-host-regexp} to a regular
expression
@vindex efs-ftp-local-host-regexp
that matches the names of hosts which can be reached using ftp, without
requiring any explicit connection to a gateway. If you have a smart ftp
client which is able to transparently go through a gateway, this will
differ from @code{efs-local-host-regexp}.

For example:

@example
     "\\.hp\\.com$\\|^[^.]*$"
@end example

will match all hosts that are in the @t{.hp.com} domain, or don't have
an explicit domain in their name, but will fail to match hosts with
explicit domains or that are specified by their ip address.

@item
Set the variable @code{efs-local-host-regexp} to machines that you have
@vindex efs-local-host-regexp
direct TCP/IP access.  In other words, you must be able to ping these
hosts.  Even if the host is accessible by a very transparent FTP
gateway, it does not qualify as a local host.  The test to determine if
machine A is local to your machine is if it is possible to ftp from
@samp{A} @emph{back} to your local machine.  Also, @code{open-network-stream}
must be able to reach the host in question.

@item
Set the variable @code{efs-gateway-tmp-name-template} to the name of
@vindex efs-gateway-tmp-name-template
a directory plus an identifying filename prefix for making temporary
files on the gateway.  For example: @code{"/tmp/hplose/ange/efs"}

@item
If the gateway and the local host share cross-mounted directories,
set the value of @code{efs-gateway-mounted-dirs-alist} accordingly. It
@vindex efs-gateway-mounted-dirs-alist
is particularly useful, but not mandatory, that the directory
of @code{efs-gateway-tmp-name-template} be cross-mounted.
@vindex efs-gateway-tmp-name-template

@item
Set the variable @code{efs-gateway-type}
@vindex efs-gateway-type
to the type gateway that you
have.  This variable is a list, the first element of which is a symbol
denoting the type of gateway.  The following arguments give data on how
to use the gateway; it depends on the gateway types---see @xref{Gateway
types}.

@end enumerate

@node Gateway types, Gateway problems, Setting up a gateway, Installing EFS
@comment  node-name,  next,  previous,  up
@section Supported gateway types

@vindex efs-gateway-type

@table @samp

@item local
This means that your local host is itself the gateway.  However,
it is necessary to use a different FTP client to gain access to
the outside world.  If the name of the FTP client were @t{xftp}, you might
set @code{efs-gateway-type} to

@example
(list 'local "xftp" efs-ftp-program-args)
@end example

If @t{xftp} required special arguments, then give them in place of
@t{efs-ftp-program-args}.
@vindex efs-ftp-program-args

@item proxy

This indicates that your gateway works by first FTP'ing to it, and
then issuing a @code{USER} command of the form

@example
USER <username>@@<host>
@end example

In this case, you might set @code{efs-gateway-type} to

@example
(list 'proxy "ftp" efs-ftp-program-args)
@end example

If you need to use a nonstandard client, such as @t{iftp}, give this
@pindex iftp
instead of @t{ftp}.  If this client needs to take special arguments,
give them instead of @t{efs-ftp-program-args}.

@item remsh

For this type of gateway, you need to start a remote shell on
your gateway, using either @t{remsh} or @t{rsh}.  You should set
@pindex remsh
@pindex rsh
@sc{efs-gateway-type} to something like

@example
(list 'remsh "remsh" nil "ftp" efs-ftp-program-args)
@end example

If you use @t{rsh} instead of @r{remsh}, change the second element from
@code{"remsh"} to @code{"rsh"}.  Note that the symbol indicating the gateway
type should still be @code{'remsh}.  If you want to pass arguments
to the remsh program, give them as the third element.  For example,
if you need to specify a user, make this @code{(list "-l" "sandy")}.
If you need to use a nonstandard FTP client, specify that as the fourth
element.  If your FTP client needs to be given special arguments,
give them instead of @code{efs-ftp-program-args}.

@item interactive

This indicates that you need to establish a login on the gateway,
using either @t{telnet} or @t{rlogin}.
@pindex telnet
@pindex rlogin
You should set @code{efs-gateway-type} to something like

@example
(list 'interactive "rlogin" nil "exec ftp" efs-ftp-program-args)
@end example

If you need to use @t{telnet}, then give @code{"telnet"} in place of the second
element @code{"rlogin"}.  If your login program needs to be given arguments,
then they should be given in the third slot.  The fourth element
is for the name of the FTP client program.  Giving this as @code{"exec ftp"},
instead of @code{"ftp"}, ensures that you are logged out if the FTP client
dies.  If the FTP client takes special arguments, give these instead
of @code{efs-ftp-program-args}.  Furthermore, you should see the documentation
at the top of @file{efs-gwp.el}.  You may need to set the variables
@code{efs-gwp-setup-term-command}, and @code{efs-gwp-prompt-pattern}.
@vindex efs-gwp-setup-term-command
@vindex efs-gwp-prompt-pattern

@item raptor
This is a type of gateway where EFS is expected to specify a gateway
user, and send a password for this user using the @code{ACCOUNT} command.
For example, to log in to @samp{foobar.edu} as sandy, while using the account
ange on the gateway, the following commands would be sent:

@example
open raptorgate.com
quote USER sandy@@foobar.edu ange
quote pass <sandy's password on foobar>
quote account <ange's password on raptorgate>
@end example

For such a gateway, you would set @code{efs-gateway-type} to

@example
(list 'raptor efs-ftp-program efs-ftp-program-args <GATEWAY USER>)
@end example

where @code{<GATEWAY USER>} is the name of your account on the gateway.  In
the above example, this would be @code{"ange"}.  You can set your gateway
password by simply setting an account password for the gateway host.
This can be done with either efs-set-account, or within your .netrc
file.  If no password is set, you will be prompted for one.

@item sidewinder
This is for the Sidewinder proxy: EFS ftp's to the proxy, and then gives
a @code{USER} command of the form @code{USER <username>@@<host>}. This
connects to @code{<host>}. Then EFS sends another @code{USER} command
@code{USER <user>}.

For such a gateway, you would set @code{efs-gateway-type} to

@example
(list 'sidewinder efs-ftp-program efs-ftp-program-args)
@end example

@item interlock
This is a type of gateway where you are expected to send a PASS
command after opening the connection to the gateway.
The precise login sequence is

@example
open interlockgate
quote PASS <sandy's password on interlockgate>
quote USER sandy@@foobar.edu
quote PASS <sandy's password on foobar.edu>
@end example

For such a gateway, you should set @code{efs-gateway-type} to

@example
(list 'interlock efs-ftp-program efs-ftp-program-args)
@end example

If you need to use a nonstandard name for your FTP client,
then replace @code{efs-ftp-program} with this name.  If your FTP client
needs to take nonstandard arguments, then replace @code{efs-ftp-program-args}
with these arguments.

If your gateway returns both a 220 code and a 331 code to the
@code{"open interlockgate"} command, then you should add a regular
expression to @code{efs-skip-msgs} that matches the 220 response.
Returning two response codes to a single FTP command is not permitted
in RFC 959.  It is not possible for efs to ignore the 220 by default,
because than it would hang for interlock installations which do not
require a password.

@item kerberos
With this gateway, you need to authenticate yourself by getting a
kerberos "ticket" first.  Usually, this is done with the kinit program.
Once authenticated, you connect to @samp{foobar.com} as user sandy with the
sequence: (Note that the @code{"-n"} argument inhibits automatic login.
Although, in manual use you probably don't use it, EFS always uses it.)

@example
iftp -n
open foobar.com
user sandy@@foobar.com
@end example
@pindex iftp

You should set @code{efs-gateway-type} to something like

@example
(list 'kerberos "iftp" efs-ftp-program-args "kinit" <KINIT-ARGS>)
@end example

If you use an FTP client other than @t{iftp}, insert its name instead of
@code{"iftp"} above.  If your FTP client needs special arguments, give
them as a list of strings in place of @code{efs-ftp-program-args}.  If
the program that you use to collect a ticket in not called
@code{"kinit"}, then give its name in place of @code{"kinit"} above.
@code{<KINIT-ARGS>} should be any arguments that you need to pass to
your kinit program, given as a list of strings.  Most likely, you will
give this as nil.

See the file @file{efs-kerberos.el} for more configuration variables.  If you
need to adjust any of these variables, please report this to us so that
we can fix them for other users.

If EFS detects that you are not authenticated to use the gateway, it
will run the kinit program automatically, prompting you for a password.
If you give a password in your @file{.netrc} file for login the value of
@code{efs-gateway-host} and user @t{kerberos}, then EFS will use this to
obtain gateway authentication.

@item Transparent gateways

If your gateway is completely transparent (for example it uses socks),
then you should set @code{efs-gateway-type} to @code{nil}.  Also, set
@code{efs-ftp-local-host-regexp} to @code{".*"}.  However,
@code{efs-local-host-regexp}, must still be set to a regular expression
matching hosts in your local domain.  EFS uses this to determine which
machines that it can open-network-stream to.  Furthermore, you should
still set @code{efs-gateway-host} to the name of your gateway machine.
That way EFS will know that this is a special machine having direct
TCP/IP access to both hosts in the outside world, and hosts in your
local domain.

@end table



@node Gateway problems, EFS and archie.el, Gateway types, Installing EFS
@comment  node-name,  next,  previous,  up
@section Common Problems with Gateways

@subsection Spurious 220 responses

Some proxy-style gateways (eg gateway type @code{'proxy} or @code{'raptor}),
return two 3-digit FTP reply codes to the @code{USER} command.
For example:

@example
open gateway.weird
220 Connected to gateway.weird
quote USER sandy@@foobar
220 Connected to foobar
331 Password required for sandy
@end example

This is wrong, according to the FTP Protocol.  Each command must return
exactly one 3-digit reply code.  It may be preceded by continuation
lines.  What should really be returned is:

@example
quote USER sandy@@foobar
331-Connected to foobar.
331 Password required for sandy.
@end example

or even

@example
quote USER sandy@@foobar
331-220 Connected to foobar.
331 Password required for sandy.
@end example

Even though the @samp{"331-220"} looks strange, it is correct protocol,
and EFS will parse it properly.

If your gateway is returning a spurious 220 to @code{USER}, a work-around
is to add a regular expression to @code{efs-skip-msgs} that matches
@vindex efs-skip-msgs
this line.  It must not match the 220 line returned to the open
command.  This work-around may not work, as some system FTP clients
also get confused by the spurious 220.  In this case, the only
solution is to patch the gateway server.  In either case, please
send a bug report to the author of your gateway software.
  
@subsection Case-sensitive parsing of FTP commands

Some gateway servers seem to treat FTP commands case-sensitively.
This is incorrect, as RFC 959 clearly states that FTP commands
are always to be case-insensitive.  If this is a problem with your
gateway server, you should send a bug report to its author.
If EFS is using a case for FTP commands that does not suit your server,
a possible work-around is to edit the efs source so that the required
case is used.  However, we will not be making any changes to the
standard EFS distribution to support this type of server behaviour.
If you need help changing the efs source, you should enquire with the
@code{efs-help} mailing list.

@node EFS and archie.el,  , Gateway problems, Installing EFS
@comment  node-name,  next,  previous,  up
@section Using archie.el with EFS

To use archie.el (by Jack Repenning) with EFS, you need at least
archie.el V3.0.1.  Problems using EFS with archie may be posted to the
EFS mailing lists.

@node Using EFS, Getting help, Installing EFS, Top
@comment  node-name,  next,  previous,  up
@chapter Using EFS

Once installed, efs operates largely transparently. All files normally
accessible to you on the internet, become part of a large virtual file
system. These files are accessed using an extended file name syntax. To
access file @code{<path>} on remote host @code{<host>} by logging in as
user @code{<user>}, you simply specify the full path of the file as
@code{/<user>@@<host>:<path>}. Nearly all Emacs file handling functions
work for remote files. It is not possible to access remote files using
shell commands in an emacs *shell* buffer, as such commands are passed
directly to the shell, and not handled by emacs.

FTP is the underlying utility that efs uses to operate on remote files.

For example, if @code{find-file} is given a filename of:

@example
/ange@@anorman:/tmp/notes
@end example

then EFS will spawn an FTP process, connect to the host 'anorman' as
user 'ange', get the file @file{/tmp/notes} and pop up a buffer containing the
contents of that file as if it were on the local file system.  If efs
needed a password to connect then it would prompt the user in the
minibuffer. For further discussion of the EFS path syntax, see the
paragraph on extended file name syntax @ref{Remote filenames}.

Full file-name completion is supported on every type of remote host.  To
do filename completion, EFS needs a listing from the remote host.
Therefore, for very slow connections, it might not save any
time. However, the listing is cached, so subsequent uses of file-name
completion will be just as fast as for local file names.

@menu
* Ports::                       Using nonstandard ports.
* Remote filenames::            The EFS extended filename syntax.
* Passwords::                   
* Using Dired::                 Browsing directories.
* Using a .netrc::              Preventing password pestering.
* EFS commands::                Interactive commands supplied by EFS.
* FTP processes::               How EFS does its work
* Tips::                        Some stuff to help you use EFS
* DL support::                  Descriptive directory listings
* Non-Unix Hosts::              Some of what you want to know
* Completion::                  Works but has its price
* Accessing the FTP process::   manually
@end menu

@node Ports, Remote filenames, Using EFS, Using EFS
@comment  node-name,  next,  previous,  up
@section Using nonstandard ports

EFS supports the use of nonstandard ports on remote hosts.  To specify
that port @code{<port>} should be used, give the host name as
@code{host#<port>}. Host names may be given in this form anywhere that
efs normally expects a host name. This includes in the @file{.netrc} file.
Logically, EFS treats different ports to correspond to different remote
hosts.

@node Remote filenames, Passwords, Ports, Using EFS
@comment  node-name,  next,  previous,  up
@section Extended filename syntax

The default full EFS path syntax is

@example
/<user>@@<host>#<port>:<path>
@end example

Both the @code{#<port>'}and @code{<user>@@} may be omitted.

If the @code{#<port>} is omitted, then the default port is taken to be 21,
the usual FTP port. For most users, the port syntax will only
very rarely be necessary.

If the @code{<user>@@} is omitted, then EFS will use a default user.  If
a login token is specified in your @file{.netrc} file, then this will be
used as the default user for @code{<host>}.  Otherwise, it is determined
based on the value of the variable @code{efs-default-user}.
@vindex efs-default-user

This EFS path syntax can be customised to a certain extent by changing a
number of variables.  To
undertake such a customization requires some knowledge about the
internal workings of EFS.

@node Passwords, Using Dired, Remote filenames, Using EFS
@comment  node-name,  next,  previous,  up
@section Passwords

A password is required for each host / user pair.  This will be prompted
for when needed, unless already set by calling @code{efs-set-passwd},
@findex efs-set-passwd
or specified in a @emph{valid} @file{~/.netrc} file.

When EFS prompts for a password, it provides defaults from its cache of
currently known passwords.  The defaults are ordered such that passwords
for accounts which have the same user name as the login which is
currently underway have priority. You can cycle through your list of
defaults with @kbd{C-n} to cycle forwards and @kbd{C-p} to cycle
backwards. The list is circular.

@subsection Passwords for anonymous user

Passwords for the user @t{anonymous} (or @t{ftp}) are handled specially.
The variable @code{efs-generate-anonymous-password} controls what
\vindex efs-generate-anonymous-password happens. If the value of this
variable is a string, then this is used as the password; if
non-@code{nil}, then a password is created from the name of the user and
the hostname of the machine on which Emacs is running; if @code{nil}
(the default) then the user is prompted for a password as normal.

@subsection Account passwords

Some FTP servers require an additional password which is sent by the
@code{ACCOUNT} command.  EFS will detect this and prompt the user for an
account password if the server expects one.  Also, an account password
can be set by calling @code{efs-set-account}, or by specifying an
@findex efs-set-account
account token in the @file{.netrc} file.

Some operating systems, such as CMS, require that @code{ACCOUNT} be used
to give a write access password for minidisks.  @code{efs-set-account} can be
used to set a write password for a specific minidisk. Also, tokens of
the form

@example
minidisk <minidisk name> <password>
@end example

may be added to host lines in your @file{.netrc} file. Minidisk tokens
must be at the end of the host line, however there may be an arbitrary
number of them for any given host.

@subsection Broken ftp clients

Many ftp clients are derivatives of the ftp command found in 4.2BSD.
This has a bug in the implementation of the @code{QUOTE} command which
causes the commands to be fed into @code{sprintf} as format strings.
For passwords, this means that @code{\%} characters are misinterpreted.
To work around this bug, set @code{efs-ftp-broken-quote} to non-NIL.

@node Using Dired, Using a .netrc, Passwords, Using EFS
@comment  node-name,  next,  previous,  up
@section Using Dired

This feature of EFS is particularly useful when file transfers, as
opposed to file editing, are the order of the day. Simply run
@code{find-file} on a directory to
get a listing of the files in that directory. For example, you might
run @code{find-file} on
@example
/anonymous@@archive.site.com:pub
@end example
@noindent
to see what's in the @file{pub} directory of your favourite archive
@cindex archive sites
site. This brings up a Dired buffer of all the files in that directory.
The @kbd{f} command is useful for looking at @file{README} files --- if
you then decide to save it @kbd{C-x C-w} is useful. You can also use
this method to copy files, but the @kbd{c} command is easier. The
@kbd{f} command can also be used to descend the directory tree by
applying it to directories.

You can also use Dired to refresh EFS's internal cache. If you
(or anybody else) has changed a remote directory since you first accessed it
with EFS, completion is not provided on any new files that EFS
does not know about. If you have
(or create) a Dired buffer which contains the modified directory,
executing @code{revert-buffer}
@findex revert-buffer
with a prefix argument (@kbd{C-u g} in the Dired buffer) 
will force a refresh of both the the buffer @emph{and also EFS's
internal cache}. If you find that filename completion isn't working on a
@cindex filename completion
file that you @emph{know} is there, this is how to fix the problem.

Dired provides facilities for maintaining an
entire directory tree in a Dired buffer, for marking files which match a
certain regexp (or you can select files interactively) and then copying
all those files to your local host (or even a different remote host).
Another useful feature is Virtual Dired, which allows you to save Dired
@cindex virtual dired
buffers of remote hosts, allowing you to browse them at a later date
without actually needing to connect to the host.

@node Using a .netrc, EFS commands, Using Dired, Using EFS
@comment  node-name,  next,  previous,  up
@section Using a .netrc file

Being prompted for passwords all the time can get rather annoying, but
there is a way to fix the problem --- a @file{.netrc} and
@code{efs-netrc-filename}.

@vindex efs-netrc-filename
if you want another
filename) file in your home directory. Basically, this is a file (in the
format of Unix @code{netrc(5)}) which
contains the names of all the machines you regularly login to, as well
as the username and password you use for that machine. You can also
supply an account password, if required.

Your @file{.netrc} file consists of lines of the form
@example
machine <machine-name> login <user-name> password <password>
@end example
@noindent
It doesn't all have to be on the one line, though: any @code{login} or
@code{password} commands in the file refer to the previous
@code{machine} command. You can also have @code{account
<account-passwd>} commands if you need special account passwords.

For example, you might have the following line in your @file{.netrc}:
@example
machine Y.local.lan.edu login myname password secret
@end example
@noindent
Then if you run @code{find-file} on the file @file{/Y.local.lan.edu:somefile}
you will automatically be logged in as user @code{myname} with password
@code{secret}. You can still login under another name and password, if
you so desire: just include the @code{user@@} part of the filename.

You may also include a default option, as follows:
@example
default login <user-name> password <password>
@end example
@noindent
which applies to any other machines not mentioned elsewhere in your
@file{.netrc}. A particularly useful application of this is with
anonymous logins:
@cindex anonymous FTP
@example
default login myname password myname@@myhost.edu
@end example
@noindent
so that accessing @file{/anyhost:anyfile} will automatically log you in
anonymously, provided the host is not mentioned in the @file{.netrc}.
Note also that if the value of @code{efs-default-user} is
@vindex efs-default-user
non-@code{nil}, its value will have precedence over the username
supplied in the default option of the @file{.netrc}.

The @file{.netrc} file is also useful in another regard: machines
included in it are provided with hostname completion. That is, for any
@cindex hostname completion
machine in the @file{.netrc}, you need only type a slash and the first
few characters of its name and then press @key{TAB} to be logged in
automatically with a username and password from the @file{.netrc} file.
So it's a good idea to put hosts you use regularly in your @file{.netrc}
as well:
@example
machine archive.site.com login anonymous password myname@@X.local.lan.edu
@end example

@node EFS commands, FTP processes, Using a .netrc, Using EFS
@comment  node-name,  next,  previous,  up
@section EFS commands

EFS supplies a few interactive commands to make connecting with
hosts a little easier.

@noindent
Command @code{efs-set-user}: Prompts for a hostname and a username.
Next time access to the host is attempted, EFS will attempt to log
in again with the new username.
@findex efs-set-user

@noindent
Command @code{efs-set-passwd}: Prompts for a hostname, user and
password. Future logins to that host as that user will use the given
password.
@findex efs-set-passwd

@noindent
Command @code{efs-set-account}: Prompts for a hostname, user and
account. Future logins to that host as that user will use the given
account.
@findex efs-set-account

Note that the effects of the above three commands only last the duration
of the current Emacs session. To make their effects permanent, you may
include them as lisp code in your @file{.emacs}:
@example
(efs-set-user HOST USER)
(efs-set-password HOST USER PASSWORD)
(efs-set-account HOST USER ACCOUNT)
@end example
@noindent
This is an alternative to using a @file{.netrc}; @xref{Using a .netrc}.

@noindent
Command @code{efs-kill-ftp-process}: kill the FTP process
associated with a given buffer's filename (by default the current
buffer). This is an easy way to achieve a resynch: any future accesses
to the remote host will cause the FTP process to be recreated.
@findex efs-kill-ftp-process

@node FTP processes, Tips, EFS commands, Using EFS
@comment  node-name,  next,  previous,  up
@section FTP processes

When EFS starts up an FTP process, it leaves it running for speed
purposes.  Some FTP servers will close the connection after a period of
time, but EFS should be able to quietly reconnect the next time that
the process is needed.

The FTP process will be killed should the associated @samp{*ftp user@@host*}
buffer be deleted.  This should not cause efs any grief.

@subsection Showing background FTP activity on the mode-line

After EFS is loaded, the command @code{efs-display-ftp-activity} will cause
@findex efs-display-ftp-activity
background FTP activity to be displayed on the mode line. The variable
@code{efs-mode-line-format} is used to determine how this data is displayed.
@vindex efs-mode-line-format
efs does not continuously track the number of active sessions, as this
would cause the display to change too rapidly. Rather, it uses a heuristic
algorithm to determine when there is a significant change in FTP activity.

@subsection File types

By default EFS will assume that all files are ASCII. If a file
being transferred matches the value of @code{efs-binary-file-name-regexp}
@vindex efs-binary-file-name-regexp
then the file will be assumed to be a binary file, and EFS will
transfer it using "type image". ASCII files will be transferred
using a transfer type which efs computes to be correct according
to its knowledge of the file system of the remote host. The
command @code{efs-prompt-for-transfer-type} toggles the variable
@findex efs-prompt-for-transfer-type
@code{efs-prompt-for-transfer-type}. When this variable is
@vindex efs-prompt-for-transfer-type
non-@code{nil}, EFS will prompt the user for the transfer type to use
for every FTP transfer.  Having this set all the time is annoying, but
it is useful to give special treatment to a small set of files.  There
is also a variable @code{efs-text-file-name-regexp}.  This is tested 
@vindex efs-text-file-name-regexp
before @code{efs-binary-file-name-regexp}, so if you set
@code{efs-text-file-name-regexp} to a non-trivial regular expression,
and @code{efs-binary-file-name-regexp} to @samp{".*"}, the result will
to make image the default transfer type.

Also, if you set @code{efs-treat-crlf-as-nl},
@vindex efs-treat-crlf-as-nl
then EFS will use type image
to transfer files between hosts whose file system differ only in that
one specifies end of line as CR-LF, and the other as NL.  This is useful
if you are transferring files between UNIX and DOS machines, and have a
package such as @file{dos-mode.el}, that handles the extra @key{^M}'s.

@subsection Status reports

Most EFS commands that talk to the FTP process output a status
message on what they are doing.  In addition, efs can take advantage
of the FTP client's @code{HASH} command to display the status of transferring
files and listing directories.  See the documentation for the variables
@code{efs-hash-mark-size},
@vindex efs-hash-mark-size
@code{efs-send-hash}
@vindex efs-send-hash
and @code{efs-verbose}
@vindex efs-verbose
for more details.

@subsection Caching of directory information

EFS keeps an internal cache of file listings from remote hosts.
If this cache gets out of synch, it can be renewed by reverting a
dired buffer for the appropriate directory (@code{dired-revert} is usually
bound to @kbd{g}).

Alternatively, you can add the following two lines to your @file{.emacs} file
if you want @kbd{C-r} to refresh EFS's cache whilst doing filename
completion.

@example
(define-key minibuffer-local-completion-map "\C-r" 'efs-re-read-dir)
(define-key minibuffer-local-must-match-map "\C-r" 'efs-re-read-dir)
@end example

@node Tips, DL support, FTP processes, Using EFS
@comment  node-name,  next,  previous,  up

@section Tips for using EFS

@enumerate
@item
Beware of compressing files on non-UNIX hosts. EFS will do it by
copying the file to the local machine, compressing it there, and then
sending it back. Binary file transfers between machines of different
architectures can be a risky business. Test things out first on some
test files. Look at @xref{Bugs}. Also, note that EFS sometimes
copies files by moving them through the local machine. Again,
be careful when doing this with binary files on non-Unix
machines.

@item
Beware that dired over ftp will use your setting of
@code{dired-no-confirm}
@vindex dired-no-confirm
(list of dired commands for which confirmation is not asked).
You might want to reconsider your setting of this variable,
because you might want confirmation for more commands on remote
direds than on local direds. For example, I strongly recommend
that you not include compress in this list. If there is enough
demand it might be a good idea to have an alist
@code{efs-dired-no-confirm} of pairs @code{( TYPE . LIST )}, where @code{TYPE} is an
operating system type and @code{LIST} is a list of commands for which
confirmation would be suppressed.  Then remote dired listings
would take their (buffer-local) value of @code{dired-no-confirm} from
this alist. Who votes for this?

@item
Some combinations of FTP clients and servers break and get out of sync
when asked to list a non-existent directory.  Some of the @t{ai.mit.edu}
machines cause this problem for some FTP clients. Using
@code{efs-kill-ftp-process}
@findex efs-kill-ftp-process
can be used to restart the ftp process, which
should get things back in synch.

@item
Some ftp servers impose a length limit on the password that can
be sent. If this limit is exceeded they may bomb in an
incomprehensible way. This sort of behaviour is common with
MVS servers. Therefore, you should beware of this possibility
if you are generating a long password (like an email address)
with @code{efs-generate-anonymous-password}.
@vindex efs-generate-anonymous-password

@item
Some antiquated FTP servers hang when asked for an @code{RNFR} command.
EFS sometimes uses this to test whether its local cache is stale.
If your server for @code{HOST} hangs when asked for this command, put

@example
(efs-set-host-property HOST 'rnfr-failed t)
@end example

in your @code{efs-ftp-startup-function-alist}
@vindex efs-ftp-startup-function-alist
entry for @code{HOST}.

@item
The FTP servers on some Unix machines have problems if the @code{ls}
command is used.  EFS will try to correct for this automatically,
and send the @code{dir} command instead.  If it fails, you can call the
function @code{efs-add-host},
@findex efs-add-host
and give the host type as @code{dumb-unix}.  Note that this change will
take effect for the current Emacs session only. To make this
specification for future emacs sessions, put

@example
(efs-add-host 'dumb-unix "hostname")
@end example

in your @file{.emacs} file. Also, please report any failure to
automatically recognize dumb unix to the "bugs" address given below, so
that we can fix the auto recognition code.

@end enumerate

@node DL support, Non-Unix Hosts, Tips, Using EFS
@comment  node-name,  next,  previous,  up
@section Descriptive directory listings

Some hosts (such as @code{cs.uwp.edu}) now use descriptive directory
listings
@cindex descriptive directory listings
@cindex extended directory listings
(which in fact contain @emph{less} information than the
standard listing!) when issued the @code{ls} command, and EFS has
been modified to cope with this. EFS can detect such listings, but
if you regularly use a remote host which uses this extended listing
format you should set the variable @code{efs-dl-dir-regexp} to a
@vindex efs-dl-dir-regexp
regular expression which matches directories using the extended listing
format. You shouldn't anchor the regexp with @samp{$} -- that way the
regexp will match subdirectories as well.  Alternatively, you can use
the interactive command @code{efs-add-dl-dir} to temporarily add a
@findex efs-add-dl-dir
remote directory for this Emacs session only.

Dired has been modified to work with such descriptive listings.

@node Non-Unix Hosts, Completion, DL support, Using EFS
@comment  node-name,  next,  previous,  up
@section Using EFS with non-Unix hosts

EFS also works with some non-Unix hosts, although not necessarily
with all the features available with Unix hosts. VMS, CMS, and MTS
systems will all now work with EFS and Dired.  It also works with a whole
bunch of others, but documentation for that has not been written yet.
This section was taken straight from the ange-ftp manual, and is
therefore in all likelihood out-of-date.

EFS should be able to automatically detect which type of host you
are using (VMS, CMS or MTS), but if it is unable to do so you can fix
the problem by setting the appropriate
@code{efs-TYPE-host-regexp} variable (where @code{TYPE} is one of
@samp{vms}, @samp{cms} or @samp{mts}) -- see below. If EFS is unable
to automatically detect any VMS, CMS or MTS host, please report this as
a bug: @xref{Bugs}.

In all cases the file-name conventions of the remote host are converted
to a UNIX-ish format, and this is the format you should use to find
files on such hosts.

@menu
* VMS support::                 Using EFS with VMS systems
* CMS support::                 Using EFS with CMS systems
* MTS support::                 Using EFS with MTS systems
@end menu

@node VMS support, CMS support, Non-Unix Hosts, Non-Unix Hosts
@comment  node-name,  next,  previous,  up
@subsection VMS support
@cindex VMS filenames
VMS filenames are of the form @code{FILE.TYPE;##}, where both
@code{FILE} and @code{TYPE} can be up to 39 characters long, and
@code{##} is an integer version number between 1 and 32,767. Valid
characters in filenames are @samp{A}-@samp{Z}, @samp{0}-@samp{9},
@samp{_}, @samp{-} and @samp{$}, however @samp{$} cannot begin a
filename and @samp{-} cannot be used as the first or last character.

Directories in VMS are converted to the standard UNIX @samp{/} notation.
For example, the VMS filename
@example
PUB$:[ANONYMOUS.SDSCPUB.NEXT]README.TXT;1
@end example
would be entered as
@noindent
@example
/PUB$$:/ANONYMOUS/SDSCPUB/NEXT/README.TXT;1
@end example
@noindent
(The double @samp{$} is required to prevent Emacs from attempting to
expand an environment variable.)  Similarly, to anonymously FTP the file
@file{[.CSV.POLICY]RULES.MEM;1} from @code{ymir.claremont.edu} you would
type @kbd{C-x C-f
/anonymous@@ymir.claremont.edu:CSV/POLICY/RULES.MEM;1}. You can always
drop off the @samp{;##} part at the end of the filename to get the
latest version.

Sandy Rutherford provides some tips for using VMS hosts:
@itemize @bullet
@item
Although VMS is not case sensitive, EMACS running under UNIX is.
Therefore, to access a VMS file, you must enter the filename with upper
case letters.

@item
To access the latest version of file under VMS, you use the filename
without the @samp{;} and version number. You should always edit the
latest version of a file. If you want to edit an earlier version, copy
it to a new file first. This has nothing to do with EFS, but is
simply good VMS operating practice. Therefore, to edit @file{FILE.TXT;3}
(say 3 is latest version), do @kbd{C-x C-f
/ymir.claremont.edu:FILE.TXT}. If you inadvertently do
@example
@kbd{C-x C-f /ymir.claremont.edu:FILE.TXT;3}
@end example
@noindent
you will find that VMS will not allow
you to save the file because it will refuse to overwrite
@file{FILE.TXT;3}, but instead will want to create @file{FILE.TXT;4},
and attach the buffer to this file. To get out of this situation,
@kbd{M-x write-file /ymir.claremont.edu:FILE.TXT} will attach the buffer
to latest version of the file. For this reason, in Dired @kbd{f}
(@code{dired-find-file}),
@findex dired-find-file
always loads the file sans version, whereas @kbd{v},
(@code{dired-view-file}),
@findex dired-view-file
always loads the explicit version number. The
reasoning being that it reasonable to view old versions of a file, but
not to edit them.

@item
VMS filenames often contain @samp{$} characters: make sure you always
quote these as @samp{$$} and watch out for the Emacs bug which fails to
quote @samp{$}'s when defaults are presented in the minibuffer: see
@xref{Bugs}.
@end itemize

EFS should automatically detect that you are using a VMS host. If
it fails to do so (which should be reported as a bug) you can use the
command @code{efs-add-vms-host}
@findex efs-add-vms-host
to inform EFS manually. For a more permanent effect, or
if you use a VMS host regularly, it's a good idea to set
@code{efs-vms-host-regexp} to a regular expression matching that
@vindex efs-vms-host-regexp
host's name. For instance, if use use @code{ymir.claremont.edu} a lot,
place the following in your .emacs:
@example
(setq efs-vms-host-regexp "^ymir.claremont.edu$")
@end example

@node CMS support, MTS support, VMS support, Non-Unix Hosts
@comment  node-name,  next,  previous,  up
@subsection CMS support
EFS has full support, including Dired support, for hosts
running CMS.

@cindex CMS filenames
CMS filenames are entered in a UNIX-y way. Minidisks are
treated as UNIX directories; for example to access the file @file{READ.ME} in
minidisk @file{*.311} on @file{cuvmb.cc.columbia.edu}, you would enter
@example
/anonymous@@cuvmb.cc.columbia.edu:/*.311/READ.ME
@end example
If @file{*.301} is the default minidisk for this account, you could access
@file{FOO.BAR} on this minidisk as
@example
/anonymous@@cuvmb.cc.columbia.edu:FOO.BAR
@end example
CMS filenames are of the form @file{FILE.TYPE}, where both @file{FILE}
and @file{TYPE} can be up to 8 characters. Again, beware that CMS
filenames are always upper case, and hence must be entered as such.

Sandy Rutherford provides some tips on using CMS hosts:
@itemize @bullet
@item
CMS machines, with the exception of anonymous accounts, nearly always
need an account password. To have EFS send an account password,
you can either include it in your @file{.netrc} (see @xref{Using a .netrc}.), or use
@code{efs-set-account}.
@findex efs-set-account

@item
EFS cannot send ``write passwords'' for a minidisk. Hopefully, we
can fix this.
@end itemize

EFS should automatically detect that you are using a CMS host. If
it fails to do so (which should be reported as a bug) you can use the
command @code{efs-add-cms-host}
@findex efs-add-cms-host
to inform EFS manually. For a more permanent effect, or
if you use a CMS host regularly, it's a good idea to set
@code{efs-cms-host-regexp} to a regular expression matching that
@vindex efs-cms-host-regexp
host's name.

@node MTS support,  , CMS support, Non-Unix Hosts
@comment  node-name,  next,  previous,  up
@subsection MTS support
EFS has full support, including Dired support, for hosts
running the Michigan terminal system, and should be able to
automatically recognise any MTS machine. 

@cindex MTS filenames
MTS filenames are entered in a UNIX-y way. For example, if your account
was @file{YYYY}, the file @file{FILE} in the account @file{XXXX:} on
@file{mtsg.ubc.ca} would be entered as
@example
/YYYY@@mtsg.ubc.ca:/XXXX:/FILE
@end example
In other words, MTS accounts are treated as UNIX directories. Of course,
to access a file in another account, you must have access permission for
it.  If @file{FILE} were in your own account, then you could enter it in a
relative path fashion as
@example
/YYYY@@mtsg.ubc.ca:FILE
@end example
MTS filenames can be up to 12 characters. Like UNIX, the structure of the
filename does not contain a type (i.e. it can have as many @samp{.}'s as you
like.) MTS filenames are always in upper case, and hence be sure to enter
them as such! MTS is not case sensitive, but an EMACS running under UNIX
is.

EFS should automatically detect that you are using an MTS host. If
it fails to do so (which should be reported as a bug) you can use the
command @code{efs-add-mts-host}
@findex efs-add-mts-host
to inform EFS manually. For a more permanent effect, or
if you use an MTS host regularly, it's a good idea to set
@code{efs-mts-host-regexp} to a regular expression matching that
@vindex efs-mts-host-regexp
host's name.

@node Completion, Accessing the FTP process, Non-Unix Hosts, Using EFS
@comment  node-name,  next,  previous,  up
@section File- and host-name completion

Full filename completion is supported on all remote UNIX hosts and some
non-Unix hosts.  Hostnames also have completion if they are mentioned in
the @file{.netrc} and no username is specified. However using the
filename completion feature can be a bit of a two edged sword.

To understand why, we need to discuss how EFS works. Whenever
EFS is asked to find a remote file (or directory) an @code{ls}
command is sent to the FTP process to list all the files in the
directory. This list is maintained in an internal cache, to provide
filename completion for later requests on that directory. EFS keeps
this cache up-to-date by monitoring Emacs commands which affect files
and directories, but if a process outside Emacs (such as another user)
changes a directory (e.g. a new file is added)
completion won't work on
that file since EFS doesn't know about it yet. The solution if to
force EFS to reread the directory and update it's cache, and the
easiest way to do that is with Dired---see @xref{Using Dired}.

Another problem is that the @code{ls} command can take a long time,
especially when dealing with distant hosts over slow links. So if you're
after a file in the @file{pub/images} directory but nothing else, it's a
better idea to type @kbd{pub/images/file @key{TAB}} than @kbd{pub/im @key{TAB}}
which will force a read of the @file{pub} directory (since
EFS needs to know how to complete @code{im}). A little extra typing
can often save a lot of waiting. Don't be afraid to use the @key{TAB}
key once the directory is cached, though.

@node Accessing the FTP process,  , Completion, Using EFS
@comment  node-name,  next,  previous,  up
@section Accessing the FTP process buffer

The FTP process used to access the remote files is available for access
if you wish. It will be in a buffer
@cindex process buffers
@cindex buffers
called @samp{"*ftp @var{remote-file-name}*"},
i.e. if you found the file
@example
/anonymous@@archive.site.com:pub/README
@end example
@noindent
there will be a buffer 
@example
*ftp anonymous@@archive.site.com*
@end example
@noindent
where all the transfers are taking place. You can have a look at the
buffer using @kbd{C-x b} as usual, and even type in commands to the FTP
process under an interface very much like @samp{shell-mode}. There are
two instances when doing this can be very useful: one is accessing
non-UNIX hosts, where Dired and filename completion may not work (if EFS
even works at all).  If you are going to use @code{mget} or @code{mput},
make sure you type @code{glob} first: EFS turns globbing off by
default. Don't be afraid of changing directories, either --- EFS always
uses absolute pathnames when communicating with the FTP process.

You can kill the FTP process at any time simply by killing this buffer.
@cindex FTP processes
@cindex processes
You can also call @code{efs-kill-ftp-process}.
@findex efs-kill-ftp-process
This won't cause EFS any grief whatsoever --- if you later make
another request to that host, EFS will simply fire up another
process and create a new buffer to hold it.

@node Getting help, Bugs, Using EFS, Top
@comment  node-name,  next,  previous,  up
@chapter Getting help

EFS has its own mailing list called @t{elisp-code-efs}.  All users of EFS
are welcome to subscribe (see below) and to discuss aspects of
EFS.

To [un]subscribe to @t{elisp-code-efs@@nongnu.org}, or to report mailer problems with the
list, point your web browser at the following address:

@example
http://lists.nongnu.org/mailman/listinfo/elisp-code-efs
@end example

For mail to be posted directly to @t{elisp-code-efs}, send to one of the
following addresses:

@example
elisp-code-efs@@nongnu.org
@end example

Mailing list archives are also available from the web page:

@example
http://lists.nongnu.org/mailman/listinfo/elisp-code-efs
@end example


@node Bugs, Concept Index, Getting help, Top
@comment  node-name,  next,  previous,  up
@chapter Bugs and Wish List


If you find any bugs or problems with this package, @strong{please}
e-mail the authors. Ideas and constructive comments are especially
welcome. So are any enhancements to EFS, preferably debugged and
documented. Also welcome are any typo fixes, corrections or additions to
this manual.

Report a bug by typing

@example
M-x efs-report-bug
@end example

or send mail to

@example
elisp-code-efs@@nongnu.org
@end example

EFS is a ``free'' program. This means that you didn't (or shouldn't
have) paid anything for it. It also means that nobody is paid to
maintain it, and the authors weren't paid for writing it.
Therefore, please try to write your bug report in a clear and
complete fashion. It will greatly enhance the probability that
something will be done about your problem.

Note that EFS relies heavily in cached information, so the bug may
depend in a complicated fashion on commands that were performed on
remote files from the beginning of your Emacs session. Trying to
reproduce your bug starting from a fresh Emacs session is usually
a good idea.

Here is a list of known bugs:

If you hit a bug in this list, please report it anyway. Most of
the bugs here remain unfixed because they are considered too
esoteric to be a high priority. If one of them gets reported
enough, we will likely change our view on that.

@enumerate
@item
EFS does not check to make sure that when creating a new file,
you provide a valid filename for the remote operating system.
If you do not, then the remote FTP server will most likely
translate your filename in some way. This may cause EFS to
get confused about what exactly is the name of the file.

@item
For CMS support, we send too many @code{cd}'s. Since @code{cd}'s are
cheap, I haven't worried about this too much. Eventually, we should have
some caching of the current minidisk. This is complicated by the fact
that some CMS servers lie about the current minidisk, so sending
redundant cd's helps us recover in this case.

@item
The code to do compression of files over ftp is not as careful as it
should be. It deletes the old remote version of the file, before
actually checking if the local to remote transfer of the compressed file
succeeds. Of course to delete the original version of the file after
transferring the compressed version back is also dangerous, because some
OS's have severe restrictions on the length of filenames, and when the
compressed version is copied back the @code{"-Z"} or @code{".Z"} may be
truncated. Then, EFS would delete the only remaining version of the
file.  Maybe EFS should make backups when it compresses files (of
course, the backup @code{"~"} could also be truncated off, sigh...).
Suggestions?

@item
If a dir listing is attempted for an empty directory on (at least
some) VMS hosts, an ftp error is given. This is really an ftp bug, and
I don't know how to get EFS work to around it.

@item
EFS gets confused by directories containing file names with embedded
newlines. A temporary solution is to add @code{"q"} to your dired
listing switches. As long as your dired listing switches also contain
@code{"l"} and either @code{"a"} or @code{"A"}, EFS will use these
switches to get listings for its internal cache. The "q" switch should
force listings to be exactly one file per line. You still will not be
able to access a file with embedded newlines, but at least it won't mess
up the parsing of the rest of the files.

@item
EFS cannot parse symlinks which have an embedded @code{" -> "} in their
name. It's alright to have an embedded @code{" -> "} in the name of any
other type of file. A fix is possible, but probably not worth the
trouble. If you disagree, send us a bug report.

@item
EFS doesn't handle context-dep. files in H-switch listings on
HP's. It wouldn't be such a big roaring deal to fix this. I'm
waiting until I get an actual bug report though.

@item
If a hard link is added or deleted, EFS will not update its
internal cache of the link count for other names of the file.
This may cause file-nlinks to return incorrectly. Reverting
any dired buffer containing other names for the file will
cause the file data to be updated, including the link counts.
A fix for this problem is known and will be eventually
implemented. How it is implemented will depend on how we decide
to handle inodes. See below.

@item
EFS is unable to parse R-switch listings from remote Unix hosts.
This is inefficient, because EFS will insist on doing individual
listings of the subdirectories to get its file information.
This may be fixed if there is enough demand.

@item
In file-attributes, EFS returns a fake inode number. Of course
this is necessary, but this inode number is not even necessarily
unique.  It is simply the sum of the characters (treated as
integers) in the host name, user name, and file name. Possible
ways to get a unique inode number are:

@enumerate
@item
Simply keep a count of all remote file in the cache, and
return the file's position in this count as a negative number.
@item
For unix systems, we could actually get at the real inode number on the
remote host, by adding an @code{"i"} to the ls switches.  The inode
numbers would then be removed from the listing returned by @code{efs-ls}, if
the caller hadn't requested the @code{"i"} switch. We could then make a
unique number out of the host name and the real inode number.
@end enumerate

@item
EFS tries to determine if a file is readable or writable by comparing
the file modes, file owner, and user name under which it is logged
into the remote host. This does not take into account groups.
We simply assume that the user belongs to all groups. As a result
we may assume that a file is writable, when in fact it is not.
Groups are tough to handle correctly over FTP. Suggestions?
(For new FTP servers, can do a @code{"QUOTE SITE EXEC groups"} to
handle this.)

@item
EFS does not interact well with certain non-standard FTP clients.
Specifically, some Linux distributions ship an ftp client with GNU
readline support compiled in.  This ftp client may produce escape
sequences which confuse EFS.  One symptom of this problem is that EFS
appears to hang after printing the following message:

@example
Logging in as user anonymous...
@end example

To fix this problem, recompile the FTP client without readline support,
or install a new FTP client without readline support and set
@code{efs-ftp-program-name} to point to the new client.
@end enumerate

@node Concept Index, Variable and function index, Bugs, Top
@comment  node-name,  next,  previous,  up
@unnumbered Concept Index

@printindex cp

@node Variable and function index,  , Concept Index, Top
@unnumbered Variable and function index

@printindex vr

@contents

@bye