/
afio.1
1667 lines (1666 loc) · 45.9 KB
/
afio.1
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
'br
.TH AFIO 1
.SH NAME
afio \- manipulate archives and files
.SH SYNOPSIS
.B ...
|
.B afio \-o
[
.I options
] archive : write (create) archive
.br
.B afio \-i
[
.I options
] archive : install (unpack) archive
.br
.B afio \-t
[
.I options
] archive : list table-of-contents of archive
.br
.B afio \-r
[
.I options
] archive : verify archive against filesystem
.br
.B afio \-p
[
.I options
] directory [ ... ] : copy files
.PP
.SH DESCRIPTION
.I Afio
manipulates groups of files, copying them within the (collective)
filesystem or between the filesystem and an
.I afio
archive.
.PP
With
.BR \-o ,
reads pathnames from the standard input
and writes an
.IR archive .
.PP
With
.BR \-t ,
reads an
.I archive
and writes a table-of-contents to the standard output.
.PP
With
.BR \-i ,
installs the contents of an
.I archive
relative to the working directory.
.PP
With
.BR \-p ,
reads pathnames from the standard input
and copies the files to each
.IR directory .
Cannot be combined with the
.B \-Z
option.
.PP
With
.BR \-r ,
reads
.IR archive
and verifies it against the filesystem. This is useful for verifying
tape archives, to ensure they have no bit errors. The verification
compares file contents, but not permission bits and non-file
filesystem entities, so it cannot be used as a reliable tool to detect
every possible change made to a filesystem.
.PP
Creates missing directories as necessary, with permissions
to match their parents.
.PP
Removes leading slashes from pathnames,
making all paths relative to the current directory.
This is a safety feature to prevent inadvertent overwriting
of system files when doing restores. To suppress this safety
feature, the
.BR \-A
option must be used while writing an archive, but also when
reading (installing), verifying, and cataloging an existing archive.
.PP
Supports compression while archiving, with the
.BR \-Z
option. Will compress individual files in the archive, not the
entire archive datastream, which makes
.I afio
compressed archives much more robust than
.I `tar\ zc'
type archives.
.PP
Supports multi-volume archives during interactive operation
(i.e., when
.I /dev/tty
is accessible and
.I SIGINT
is not being ignored).
.PP
.SH OPTIONS
.TP 13
.BI "\-@ " address
Send email to
.I address
when a volume change (tape change, floppy change) is needed, and also when
the entire operation is complete. Uses
.IR sendmail (1)
to send the mail.
.TP
.B \-a
Preserve the last access times (atimes) of the files read when
making or verifying an archive.
.B Warning:
if this option is used,
.I afio
will change the last inode changed times (ctimes) of these files.
Thus, this option cannot be used together with an incremental backup
scheme that relies on the ctimes being preserved.
.TP
.BI \-b "\ size"
Read or write
.IR size -character
archive blocks.
Suffices of
.BR b ,
.BR k ,
.B m
and
.B g
denote multiples of
.IR 512 ,
.IR kilobytes ,
.IR megabytes
and
.IR gigabytes ,
respectively.
Defaults to
.I 5120
for compatibility with
.IR cpio (1).
In some cases, notably when using
.I ftape
with some tape drives,
.B \-b 10k
is needed for compatibility. Note that
.B \-b 10k
is the default block size used by
.IR tar (1),
so it is usually a good choice if the tape setup is known to work
with
.IR tar (1).
.TP
.BI \-c "\ count"
Buffer
.I count
archive blocks between I/O operations. A large
.I count
is recommended for efficient use with streaming magnetic tape drives, in
order to reduce the number of tape stops and restarts.
.TP
.B \-d
Don't create missing directories.
.TP
.BI \-e "\ bound"
Pad the archive to a multiple of
.I bound
characters.
Recognizes the same suffices as
.BR \-s .
Defaults to
.I 1x\^
(the
.B \-b
block size)
for compatibility with
.IR cpio (1).
.TP
.B \-f
Spawn a child process to actually write to the archive; provides
a clumsy form of double-buffering.
Requires
.B \-s
for multi-volume archive support.
.TP
.B \-g
Change to input file directories. Avoids quadratic filesystem
behavior with long similar pathnames. Requires all absolute
pathnames, including those for the
.B \-o
.I archive
and the
.B \-p
.IR directories .
.TP
.B \-h
Follow symbolic links, treating them as ordinary files and directories.
.TP
.B \-j
Don't generate sparse filesystem blocks on restoring files.
By default,
.I afio
creates sparse filesystem blocks (with
.IR lseek (2))
when possible when restoring files from an archive,
but not if these files were stored in a compressed form. Unless stored in
a compressed form, sparse files are not archived efficiently:
they will take space equal to the full file length.
(The sparse file handling in
.I afio
does not make much sense except in a historical way.)
.TP
.B \-k
Rather
than complaining about unrecognizable input,
skip unreadable data (or partial file contents) at the
.I beginning
of the archive file being read, and search for the next valid archive header.
This option is needed to deal with certain types of backup media damage.
It is also useful to support quick
selective restores from multi-volume archives, or
from searchable block devices, if the volume or location of the file to be
restored is known in advance (see the
.B \-B
option).
If, for example, a selective restore is done with
the fourth volume of a multi-volume afio archive,
then the
.B \-k
option needs to be used, else
.I afio
will complain about the input not being a well-formed archive.
.TP
.B \-l
With
.BR \-o ,
write file contents with each hard link.
.sp
With
.BR \-t ,
report hard links.
.sp
With
.BR \-p ,
attempt to link files rather than copying them.
.TP
.B \-m
Mark output files with a common current timestamp
(rather than with input file modification times).
.TP
.B \-n
Protect newer existing files (comparing file modification times).
.TP
.BI \-s "\ size"
Restrict each portion of a multi-volume archive to
.I size
characters. This
option recognizes the same size suffices as
.BR \-b .
Also, the suffix
.B x
denotes a multiple of the
.B \-b
block size (and must follow any
.B \-b
specification).
.I size
can be a single size or a comma-seperated list of sizes,
for example '2m,5m,8m', to specify different sizes for the
subsequent volumes. If there are more volumes than sizes, the last
specified size is used for all remaining volumes.
If this option is used, the special character sequences
.B %V
and
.B %S
in the input/output filename or command string are replaced by the
current volume number and volume size. Use
.B %%
to produce a single % character.
The
.B \-s
option is useful
with finite-length devices which do not return short
counts at end of media (sigh); output to magnetic tape typically
falls into this category. When an archive is being read or written, using
.B \-s
causes
.I afio
to prompt for the next volume if the specified volume length is reached.
The
.B \-s
option will also cause
.I afio
to prompt if there is a premature EOF while reading the input.
The special case
.B \-s 0
will activate this prompting for the next volume on premature EOF without
setting a volume length.
When writing an archive,
.I afio
will prompt for the next volume on end-of-media, even without
.B \-s 0
being supplied, if the device is capable of reporting end-of-media.
If the volume
.I size
specified is not a multiple of the block size set with the
.B \-b
option, then
.I afio(1)
will silently round down the volume size to the nearest multiple of
the block size. This rounding down can be suppressed using the
.B \-9
option: if
.B \-9
is used,
.I afio(1)
will write a small block of data, smaller than the
.B \-b
size, at the end of the volume to completely fill it to the specified
size. Some devices are not able to handle such small block writes.
.TP
.B \-u
Report files with unseen links.
.TP
.B \-v
Verbose. Report pathnames (to stderr) as they are processed. When used with
.BR \-t ,
gives an
.I "ls \-l"
style report (including link information) to stdout instead.
When used twice
.RB ( \-vv )
with
.BR \-o ,
gives an
.I "ls \-l"
style report to stdout while writing the archive. (But this use of
.B \-vv
will not work if the archive is also being written to stdout.)
.TP
.BI \-w "\ filename"
Treats each line in
.I filename
as an
.B \-y
pattern, see
.BR \-y .
.TP
.B \-x
Retain file ownership and setuid/setgid permissions.
This is the default for the super-user; he may use
.B \-X
to override it.
.TP
.BI \-y "\ pattern"
Restrict processing of files to names matching shell wildcard pattern
.IR pattern .
Use this flag once for each pattern to be recognized.
With the possible exception of the presence of a leading slash, the
complete file name as appearing in the archive table-of-contents must
match the pattern, for example the file name 'etc/passwd' is matched
by the pattern '*passwd' but NOT by the pattern 'passwd'. See
.B `man 7 glob'
for more information on shell wildcard pattern matching.
The only difference with shell wildcard pattern matching is that in
.I afio
the wildcards will also match '/' characters in file
names. For example the pattern '/usr/src/*' will match the
file name '/usr/src/linux/Makefile', and any other file name
starting with '/usr/src'. Unless the
.B \-S
option is given, any leading slash in the pattern or the filename is
ignored when matching,
e.g.
.I /etc/passwd
will match
.IR etc/passwd .
Use
.B \-Y
to supply patterns which are
.I not
to be processed.
.B \-Y
overrides
.B \-y
if a filename matches both.
See also
.BR \-w\ and\ \-W .
See also the
.B \-7
option, which can be used to modify the meaning of
.BR \-y ", " \-Y ", " \-w ", and " \-W
when literal matching without wildcard processing is needed.
.B Note:
if
.I afio
was compiled without using the GNU fnmatch library, then the full
shell wildcard pattern syntax cannot be used,
and matching support is limited to patterns which are a full
literal file name and patterns which end in '*'.
.TP
.B \-z
Print execution statistics. This is meant for human consumption;
use by other programs is officially discouraged.
.TP
.B \-A
Do not turn absolute paths into relative paths. That is don't remove
the leading slash. Applies to the path names written in an archive,
but also to the path names read out of an archive during read (install),
verify, and cataloging operations.
.TP
.B \-B
If the
.B \-v
option is used, prints the byte offset of the start of each file in
the archive.
If your tape drive can start reading at any position in an
archive, the output of
.B \-B
can be useful for doing quick selective restores.
.TP
.BI \-D "\ controlscript"
Set the control script name to
.IR controlscript ,
see the section on
.B control files
below.
.TP
.BI \-E "\ [+]filename" " | \-E CS | \-E CI"
While creating an archive with compressed files using the
.B \-Z
option, disable (attempts at) compression for files with
particular extensions.
This option can be used to speed up the creation of the archive, by
making
.I afio
avoid trying to use
.I gzip
on files that contain compressed data already.
By default, if no specific
.B \-E
option is given, all files with the extensions
'br the two START_ and END_ comments below are used by the makefile to create
'br the compiled-in defaults for the \-E option.
'br NOTE: the awk script called by in the makefile disregards all
'br FIRST words on each line below,
'br i.e. it disregards the .I typesetting commands and the word and.
'br so BE CAREFUL TO TAKE THIS INTO ACCOUNT if you edit the text below,
'br else the awk script might miss some extensions, or take some
'br common words you add as default extensions.
'br START_EXT_LIST
.I .Z .z .gz .bz2 .tgz
.I .arc .zip .rar .lzh .lha
.I .uc2 .tpz .taz .tgz .rpm .zoo .deb
.I .gif .jpeg .jpg .tif .tiff .png .pdf
.I .arj .avi .bgb .cab .cpn .hqx .jar
.I .mp3 .mpg .mpq .pic .pkz .psn .sit .ogg
and
.I .smk
'br END_EXT_LIST
will not be compressed.
Also by default, the file extension matching is case-insensitive (to do the
right thing with respect to MS-DOS based filesystems).
The
.BI \-E "\ filename"
form of this option will replace the default list of file extensions
by reading a new list of file extensions, separated by whitespace, from
.IR filename .
.I filename
may contain comments preceded by a #. The extensions in
.I filename
should usually all start with a dot, but they do not need to start with a
dot, for example the extension 'tz' will match the file name 'hertz'.
The
.BI \-E "\ +filename"
form (with a + sign in front of
.IR filename )
can be
used to specify extensions in addition to the built-in
default list, instead of replacing the whole default list.
To make extension matching case-sensitive, add the special option form
.B \-E CS
to the command line. The form
.B \-E CI
invokes the (default) case-insensitive comparison.
See also the
.B \-6
option, which offers an additional way to suppress compression.
.TP
.B \-F
This is a floppy disk,
.B \-s
is required. Causes floppy writing in
.B O_SYNC
mode under Linux. With kernel version 1.1.54 and above, this allows
.I afio
to detect some floppy errors while writing.
Uses shared memory if compiled in otherwise mallocs as needed (a 3b1
will not be able to malloc the needed memory w/o shared memory),
.I afio
assumes either way you can malloc/shmalloc a chunck of memory
the size of one disk. Examples: 795k: 3.5" (720k drive), 316k (360k drive)
.nf
At the end of each disk this message occurs:
Ready for disk [#] on [output]
(remove the disk when the light goes out)
Type "go" (or "GO") when ready to proceed
(or "quit" to abort):
.fi
.TP
.BI \-G "\ factor"
Specifies the
.IR gzip (1)
compression speed factor, used when compressing files with the
.B \-Z
option.
Factor 1 is the fastest with least compression, 9 is slowest with best
compression.
The default value is 6. See also the
.IR gzip (1)
manual page.
If you have a slow machine or a fast backup medium, you may want to
specify a low value for
.I factor
to speed up the backup. On large (>200k) files,
.B \-G 1
typically zips twice as fast as
.BR "\-G 6" ,
while still achieving a better result than
.IR compress "(1)."
The zip speed for small files is mainly determined by the invocation time
of
.I gzip
(1), see the
.B \-T
option.
.TP
.BI "\-H " promptscript
Specify a script to run, in stead of using the normal prompt, before
advancing to the next archive volume. The script will be run with the
volume number, archive specification, and the reason for changing to
the next volume as arguments. The script
should exit with 0 for OK and 1 for abort, other exit codes will be
treated as fatal errors.
.I afio
executes the script by taking the
.I promptscript
string, appending the arguments, and then calling the shell to execute
the resulting command line. This means that a general-purpose
prompt script can be supplied with additional arguments, via the
.I afio
command line, by using a
.B \-H
option value like
\-H "generic_promptscript additional_arg_1 additional_arg_2".\\
.TP
.B \-J
Try to continue after a media write error when doing a backup (normal
behavior is to abort with a fatal error).
.TP
.B \-K
Verify the output against what is in the memory copy of the disk (\-F required).
If the writing or verifying fails the following menu pops up
.nf
[Writing/Verify] of disk [disk #] has FAILED!
Enter 1 to RETRY this disk
Enter 2 to REFORMAT this disk before a RETRY
Enter quit to ABORT this backup
.fi
Currently,
.I afio
will not process the answers 1 and 2 in the right way. The menu above
is only useful in that it signifies that something is wrong.
.TP
.BI "\-L " Log_file_path
Specify the name of the file to log errors and the final totals to.
.TP
.BI \-M "\ size
Specifies the maximum amount of memory to use for the temporary storage of
compression results when using the
.B \-Z
option. The default is
.B \-M 250m
(250 megabytes). If the compressed version of a file is larger than
this (or if
.I afio
runs out of virtual memory),
.IR gzip (1)
is run twice of the file,
the first time to determine the length of the result, the second time
to get the compressed data itself.
.TP
.BI \-P "\ progname"
Use the program
.I progname
instead of the standard
.IR gzip (1)
for compression and decompression with the
.B \-Z
option. For example, use the options
.B \-Z \-P bzip2
to write and install archives using
.IR bzip2 (1)
compression. If
.I progname
does not have command line options (\-c, \-d, and \-<number>) in the style of
.IR gzip (1)
then the
.B \-Q
option can be used to supply the right options.
The compression program used must have the property that, if the output
file size exceeds the value of the
.B \-M
option,
then when the compression program is run for a second time on the same input,
it must produce an output with exactly the same size. (See also the
.B \-M
option description.) The GnuPG
.RB ( gpg )
encryption program does not satisfy this lenght-preserving criterion unless
its built-in compression is disabled (see examples in the afio source script3/
directory).
See also the
.BR \-Q ,
.B \-U
and
.B \-3
options.
.TP
.BI \-Q "\ opt"
Pass the option
.I "opt"
to the compression or decompression program used with the
.B \-Z
option. For passing multiple options, use
.B \-Q
multiple times. If no
.B \-Q
flag is present, the standard options are passed. The standard
options are
.B \-c \-6
when the program is called for compression and
.B \-c \-d
when the program is called for decompression. Use the special case
.B \-Q
""
if no options at all are to be passed to the program.
.TP
.BI \-R "\ Disk format command string"
This is the command that is run when you enter 2 to reformat the disk after
a failed verify.
The default (fdformat /dev/fd0H1440) can be changed
to a given system's default by editing the Makefile.
You are also prompted for formatting whenever a disk change
is requested.
.TP
.BI \-S
Do not ignore a leading slash in the pattern or the file name when matching
.B \-y
and
.B \-Y
patterns. See also
.BR \-A .
.TP
.BI \-T "\ threshold"
Only compress a file when using the
.B \-Z
option if its length is at least
.IR threshold .
The default is
.BR "\-T 0k" .
This is useful if you have a slow machine or a fast backup medium.
Specifying
.B "\-T 3k"
typically halves the number of invocations of
.IR gzip (1),
saving some 30% computation time, while creating an archive
that is only 5% longer. The combination
.B \-T 8k \-G 1
typically saves 70% computation time and gives a 20% size increase.
The latter combination may be a good alternative to not using
.B \-Z
at all. These figures of course depend heavily on the kind of files
in the archive and the processor - i/o speed ratio on your machine.
See also the
.B \-2
option.
.TP
.B \-U
If used with the
.B \-Z
option, forces compressed versions to be stored of all files, even if
the compressed versions are bigger than the original versions, and
disregarding any (default) values of the
.B \-T
and
.B \-2
options. This is useful when the
.B \-P
and
.B \-Q
options are used to replace the compression program
.I gzip
with an encryption program in order to make an archive with encrypted files.
Due to internal limitations of
.IR afio ,
use of this flag forces the writing of file content with each hard
linked file, rather than only once for every set of hard linked files.
.B WARNING:
use of the \-U option
will also cause compression (or whatever operation the
.B \-P
option indicates) on files larger than 2 GB, if these
are present in the input. Not all compression programs might handle
such huge files correctly (recent Linux versions of gzip, bzip2, and
gpg have all been tested and seem to work OK). If your setup is
obscure, some testing might be warranted.
.TP
.BI \-W "\ filename"
Treats each line in
.I filename
as an
.B \-Y
pattern, see
.BR \-Y .
.TP
.BI \-Y "\ pattern"
Do
.I not
process files whose names match shell wildcard pattern
.IR pattern .
See also
.BR "\-y " and " \-W" .
.TP
.B \-Z
Compress the files that go into the archive when creating an archive,
or uncompress them again when installing an archive.
.I afio \-Z
will compress each file in the archive individually, while keeping the archive
headers uncompressed. Compared to
.I tar zc
style archives,
.I afio \-Z
archives are therefore much more fault-tolerant
against read errors on the backup medium.
When creating an archive with the
.I \-Z
option,
.I afio
will run
.I gzip
on each file encountered, and, if the result is smaller than the original,
store the compressed version of the file.
Requires
.IR gzip (1)
to be in your path. Mainly to speed up
.I afio
operation, compression is not attempted on a file if:
1) the file is very small (see the
.B \-T
option),
2) the file is very large (see the
.B \-2
option),
3) the file has a certain extension, so it probably contains
compressed data already (see the
.B \-E
option),
4) the file pathname matches a certain pattern, as set by the
.B \-6
option,
5) the file has hard links (this due to an internal limitation of afio,
but this limitation does not apply if the
.B \-l
option is also used).
Regardless of the above, if the
.B \-U
option is used then the compression program is always run, and the
compressed result is always stored.
When installing an archive with compressed files, the
.B \-Z
option needs to be used in order to make afio automatically uncompress
the files that it compressed earlier.
The
.B \-P
option can be used to do the (un)compression with programs other than
.IR gzip ,
see the
.B \-P
(and
.B \-Q
and
.BR \-3 )
options in this manpage for details.
See also the
.BR \-G
option which provides yet another way to tune the compression process.
.TP
.B \-0
Use filenames terminated with '\\0' instead
of '\\n'. When used as follows:
.IR "find ... \-print0 | afio \-o \-0 ..." ,
it ensures that any input filename can be handled,
even a file name containing newlines. When used as
.IR "afio \-t \-0 ... | ..." ,
this allows the table of contents output to be parsed unambiguosly
even if the filenames contain newlines. The
.B \-0
option also affects the parsing of the files supplied by
.B "\-w file"
and
.B "\-W file"
options: if the option
.B \-0
precedes them in the command line then the pattern lines contained in the
.BR file s
should be terminated with '\\0' in stead of '\\n'. A second use of
.B \-0
toggles the option. This can be useful when using multiple pattern files
or when combining with the
.B \-t
option.
.TP
.BI \-1 "\ warnings-to-ignore"
Control if
.IR afio (1)
should exit with a nonzero code after printing certain warning messages,
and if certain warning messages should be printed at all.
This option is sometimes useful when calling
.IR afio (1)
from inside a backup script or program.
.IR afio (1)
will exit with a nonzero code on encountering
various 'hard' errors, and also (with the default value of the
.B \-1
option) when it has printed
certain warning messages during execution.
.I warnings-to-ignore
is a list of letters which determines the behavior related to warning messages.
The default value for this option is
.BR "\-1 mc" .
For
.I afio
versions 2.4.3 and earlier, the default was
.BR "\-1 a" .
For
.I afio
versions 2.4.4 and 2.4.5, the default was
.BR "\-1 ''" .
The defined
.I warnings-to-ignore
letters are as follows.
.B a
is for for ignoring
.IR a ll
possible warnings on exit: if this letter is used,
the printing of a warning message will
never cause a nonzero exit code.
.B m
is for ignoring in the exit code any warning about
.IR m issing
files, which will be printed when, on
creating an archive, a file whose name was read from the standard
input is not found.
.B c
is for ignoring in the exit code the warning that the
archive being created will not be not fully compatible with
.IR c pio
or afio versions 2.4.7 or lower.
.B C
is the same as
.IR c ,
but in addition the warning message will not even be printed.
.B M
will suppress the printing of all warning messages asssociated with
.IR M ultivolume
archive handling, messages like "Output limit reached" and
"Continuing".
.B d
is for ignoring in the exit code any warnings about changed
files, which will be printed when, on creating an archive, a file that
is being archived changes while it is being written into the archive,
where the changing is detected by examining the file modification time
stamp.
.B r
is for ignoring certain warnings during the verify (\-r) operation.
If this letter is used, some verification errors that are
very probably due to changes in the filesystem, during or after
the backup was made,
are ignored in determining the exit code.
The two verification errors that are ignored are:
1) a file in the archive is no
longer present on the filesystem, and 2) the file contents in the
archive and on the filesystem are different, but the file lengths
or the file modification times are also different, so the
difference in contents is probably due to the file on the file
system having been changed.
.B n
is for ignoring in the exit code a particular class of
.IR n o-such-file
warnings: it ignores these warnings when they happen after the file has already
been successfully opened. This unusual warning situation can occur
when archiving files on Windows smbfs filesystems -- due to a Windows problem,
smbfs files with non-ASCII characters in their names
can sometimes be opened but not read. When the
.B \-Z
option is used, the
.I n
letter function is (currently) only implemented for files with sizes
smaller than indicated by the
.B \-T
option, so in that case the
.B \-T
option is also needed for this letter to have any effect.
.TP
.BI "\-2 " maximum-file-size-to-compress
Do not compress any files which
are larger than this size when making a compressed archive
with the
.B \-Z
option. The default value is
.BR "\-2 200m"
(200 Megabytes). This maximum size cutoff lowers the risk that a major portion
of a large file
will be irrecoverable due to small media errors. If a media error occurs
while reading a file that
.I afio
has stored in a compressed form, then
.I afio
and
.I gzip
will not be able to restore the entire remainder of that file.
This is usually an acceptable risk for small files. However for very
large files the risk of loosing a large amount of data because
of this effect will usually be too big. The special case
.B "\-2 0"
eliminates any maximum size cutoff.
.TP
.BI "\-3 " filedescriptor-nr
Rewind the filedescriptor before invoking the (un)compression program
if using the
.B \-Z
option. This
is useful when the
.B \-P
and
.B \-Q
options are used to replace the compression program
.I gzip
with some types of encryption programs in order to make or read an archive
with encrypted files. The rewinding is needed to interface
correctly with some encryption programs that read their key from an open
filedescriptor. If the
.B \-P
program name matches 'pgp' or 'gpg', then the
.B \-3
option
.I must
be used to avoid
.IR afio (1)
reporting an error. Use the special case
.B "\-3 0"
to suppress the error message without rewinding any file descriptor.
The
.B "\-3 0"
option may also be needed to successfully read back encrypted archives
made with
.I afio
version 2.4.5 and older.
.TP
.B \-4
(Deprecated, the intended effect of this option is now
archived by default as long as the
.B \-5
option is not used. This option could still be useful for compatibility
with machines running an older version of
.IR afio .)
Write archive with the `extended ASCII' format headers which use 4-byte
inode numbers. Archives using the extended ASCII format headers
are
.B not
compatible with any other archiver. This option was useful for reliably
creating and restoring sets of files with many internal
hard links, for example a news spool.
.TP
.B \-5
Refuse to create an archive that is incompatible with
.IR cpio (1).
If this option is used,
.I afio
will never write any `large ASCII' file headers that are incompatible with
.IR cpio (1),
but fail with an error code instead.
See the ARCHIVE PORTABILITY section above for more information on the
use of `large ASCII' file headers.