← Back to branch summary

~ubuntu-branches/ubuntu/quantal/cmake/quantal

« back to all changes in this revision

Viewing changes to Utilities/cmlibarchive/libarchive/tar.5

  • Committer: Package Import Robot
  • Author(s): Felix Geyer
  • Date: 2012-04-30 12:14:32 UTC
  • mfrom: (3.1.30 sid)
  • Revision ID: package-import@ubuntu.com-20120430121432-rqh2fjl3zcblehh5
Tags: 2.8.8-2ubuntu1
* Merge from Debian unstable, remaining changes:
  - Add xfail_compiler_flag.diff: Mark compiler flag tests as expected
    failures.
  - Add ubuntu_qt_import_dir_variable.diff: define QT_IMPORTS_DIR even
    when that dir does not exist.
* Remove increase_ctest_test_timeout.diff, merged upstream.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Utilities/cmlibarchive/libarchive/tar.5
22
22
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23
23
.\" SUCH DAMAGE.
24
24
.\"
25
 
.\" $FreeBSD: src/lib/libarchive/tar.5,v 1.18 2008/05/26 17:00:23 kientzle Exp $
 
25
.\" $FreeBSD: head/lib/libarchive/tar.5 201077 2009-12-28 01:50:23Z kientzle $
26
26
.\"
27
 
.Dd April 19, 2009
28
 
.Dt tar 5
 
27
.Dd December 27, 2009
 
28
.Dt TAR 5
29
29
.Os
30
30
.Sh NAME
31
31
.Nm tar
55
55
These
56
56
.Dq blocks
57
57
are always a multiple of the record size.
58
 
The most common block size\(emand the maximum supported by historic
59
 
implementations\(emis 10240 bytes or 20 records.
 
58
The maximum block size supported by early
 
59
implementations was 10240 bytes or 20 records.
 
60
This is still the default for most implementations
 
61
although block sizes of 1MiB (2048 records) or larger are
 
62
commonly used with modern high-speed tape drives.
60
63
(Note: the terms
61
64
.Dq block
62
65
and
78
81
archive consists of the following:
79
82
.Bd -literal -offset indent
80
83
struct header_old_tar {
81
 
    char name[100];
82
 
    char mode[8];
83
 
    char uid[8];
84
 
    char gid[8];
85
 
    char size[12];
86
 
    char mtime[12];
87
 
    char checksum[8];
88
 
    char linkflag[1];
89
 
    char linkname[100];
90
 
    char pad[255];
 
84
        char name[100];
 
85
        char mode[8];
 
86
        char uid[8];
 
87
        char gid[8];
 
88
        char size[12];
 
89
        char mtime[12];
 
90
        char checksum[8];
 
91
        char linkflag[1];
 
92
        char linkname[100];
 
93
        char pad[255];
91
94
};
92
95
.Ed
93
96
All unused bytes in the header record are filled with nulls.
168
171
format described below with the following variations:
169
172
.Bl -bullet -compact -width indent
170
173
.It
171
 
The magic value is
172
 
.Dq ustar\ \&
173
 
(note the following space).
 
174
The magic value consists of the five characters
 
175
.Dq ustar
 
176
followed by a space.
174
177
The version field contains a space character followed by a null.
175
178
.It
176
179
The numeric fields are generally filled with leading spaces
193
196
It extends the historic format with new fields:
194
197
.Bd -literal -offset indent
195
198
struct header_posix_ustar {
196
 
    char name[100];
197
 
    char mode[8];
198
 
    char uid[8];
199
 
    char gid[8];
200
 
    char size[12];
201
 
    char mtime[12];
202
 
    char checksum[8];
203
 
    char typeflag[1];
204
 
    char linkname[100];
205
 
    char magic[6];
206
 
    char version[2];
207
 
    char uname[32];
208
 
    char gname[32];
209
 
    char devmajor[8];
210
 
    char devminor[8];
211
 
    char prefix[155];
212
 
    char pad[12];
 
199
        char name[100];
 
200
        char mode[8];
 
201
        char uid[8];
 
202
        char gid[8];
 
203
        char size[12];
 
204
        char mtime[12];
 
205
        char checksum[8];
 
206
        char typeflag[1];
 
207
        char linkname[100];
 
208
        char magic[6];
 
209
        char version[2];
 
210
        char uname[32];
 
211
        char gname[32];
 
212
        char devmajor[8];
 
213
        char devminor[8];
 
214
        char prefix[155];
 
215
        char pad[12];
213
216
};
214
217
.Ed
215
218
.Bl -tag -width indent
272
275
the system.
273
276
.It Va devmajor , Va devminor
274
277
Major and minor numbers for character device or block device entry.
275
 
.It Va prefix
276
 
First part of pathname.
 
278
.It Va name , Va prefix
277
279
If the pathname is too long to fit in the 100 bytes provided by the standard
278
280
format, it can be split at any
279
281
.Pa /
280
 
character with the first portion going here.
 
282
character with the first portion going into the prefix field.
281
283
If the prefix field is not empty, the reader will prepend
282
284
the prefix value and a
283
285
.Pa /
284
286
character to the regular name field to obtain the full pathname.
 
287
The standard does not require a trailing
 
288
.Pa /
 
289
character on directory names, though most implementations still
 
290
include this for compatibility reasons.
285
291
.El
286
292
.Pp
287
293
Note that all unused bytes must be set to
308
314
happens to have a
309
315
.Pa /
310
316
as the 156th character.)
311
 
POSIX requires numeric fields to be zero-padded in the front, and allows
 
317
POSIX requires numeric fields to be zero-padded in the front, and requires
312
318
them to be terminated with either space or
313
319
.Dv NUL
314
320
characters.
316
322
Currently, most tar implementations comply with the ustar
317
323
format, occasionally extending it by adding new fields to the
318
324
blank area at the end of the header record.
 
325
.Ss Numeric Extensions
 
326
There have been several attempts to extend the range of sizes
 
327
or times supported by modifying how numbers are stored in the
 
328
header.
 
329
.Pp
 
330
One obvious extension to increase the size of files is to
 
331
eliminate the terminating characters from the various
 
332
numeric fields.
 
333
For example, the standard only allows the size field to contain
 
334
11 octal digits, reserving the twelfth byte for a trailing
 
335
NUL character.
 
336
Allowing 12 octal digits allows file sizes up to 64 GB.
 
337
.Pp
 
338
Another extension, utilized by GNU tar, star, and other newer
 
339
.Nm
 
340
implementations, permits binary numbers in the standard numeric fields.
 
341
This is flagged by setting the high bit of the first byte.
 
342
The remainder of the field is treated as a signed twos-complement
 
343
value.
 
344
This permits 95-bit values for the length and time fields
 
345
and 63-bit values for the uid, gid, and device numbers.
 
346
In particular, this provides a consistent way to handle
 
347
negative time values.
 
348
GNU tar supports this extension for the
 
349
length, mtime, ctime, and atime fields.
 
350
Joerg Schilling's star program and the libarchive library support
 
351
this extension for all numeric fields.
 
352
Note that this extension is largely obsoleted by the extended
 
353
attribute record provided by the pax interchange format.
 
354
.Pp
 
355
Another early GNU extension allowed base-64 values rather than octal.
 
356
This extension was short-lived and is no longer supported by any
 
357
implementation.
319
358
.Ss Pax Interchange Format
320
359
There are many attributes that cannot be portably stored in a
321
360
POSIX ustar archive.
359
398
.It Cm atime , Cm ctime , Cm mtime
360
399
File access, inode change, and modification times.
361
400
These fields can be negative or include a decimal point and a fractional value.
 
401
.It Cm hdrcharset
 
402
The character set used by the pax extension values.
 
403
By default, all textual values in the pax extended attributes
 
404
are assumed to be in UTF-8, including pathnames, user names,
 
405
and group names.
 
406
In some cases, it is not possible to translate local
 
407
conventions into UTF-8.
 
408
If this key is present and the value is the six-character ASCII string
 
409
.Dq BINARY ,
 
410
then all textual values are assumed to be in a platform-dependent
 
411
multi-byte encoding.
 
412
Note that there are only two valid values for this key:
 
413
.Dq BINARY
 
414
or
 
415
.Dq ISO-IR\ 10646\ 2000\ UTF-8 .
 
416
No other values are permitted by the standard, and
 
417
the latter value should generally not be used as it is the
 
418
default when this key is not specified.
 
419
In particular, this flag should not be used as a general
 
420
mechanism to allow filenames to be stored in arbitrary
 
421
encodings.
362
422
.It Cm uname , Cm uid , Cm gname , Cm gid
363
423
User name, group name, and numeric UID and GID values.
364
424
The user name and group name stored here are encoded in UTF8
402
462
.Cm SCHILY.*
403
463
extensions can store all of the data from
404
464
.Va struct stat .
 
465
.It Cm LIBARCHIVE.*
 
466
Vendor-specific attributes used by the
 
467
.Nm libarchive
 
468
library and programs that use it.
 
469
.It Cm LIBARCHIVE.creationtime
 
470
The time when the file was created.
 
471
(This should not be confused with the POSIX
 
472
.Dq ctime
 
473
attribute, which refers to the time when the file
 
474
metadata was last changed.)
405
475
.It Cm LIBARCHIVE.xattr. Ns Ar namespace Ns . Ns Ar key
406
476
Libarchive stores POSIX.1e-style extended attributes using
407
477
keys of this form.
479
549
GNU tar archives.
480
550
.Bd -literal -offset indent
481
551
struct header_gnu_tar {
482
 
    char name[100];
483
 
    char mode[8];
484
 
    char uid[8];
485
 
    char gid[8];
486
 
    char size[12];
487
 
    char mtime[12];
488
 
    char checksum[8];
489
 
    char typeflag[1];
490
 
    char linkname[100];
491
 
    char magic[6];
492
 
    char version[2];
493
 
    char uname[32];
494
 
    char gname[32];
495
 
    char devmajor[8];
496
 
    char devminor[8];
497
 
    char atime[12];
498
 
    char ctime[12];
499
 
    char offset[12];
500
 
    char longnames[4];
501
 
    char unused[1];
502
 
    struct {
503
 
        char offset[12];
504
 
        char numbytes[12];
505
 
    } sparse[4];
506
 
    char isextended[1];
507
 
    char realsize[12];
508
 
    char pad[17];
 
552
        char name[100];
 
553
        char mode[8];
 
554
        char uid[8];
 
555
        char gid[8];
 
556
        char size[12];
 
557
        char mtime[12];
 
558
        char checksum[8];
 
559
        char typeflag[1];
 
560
        char linkname[100];
 
561
        char magic[6];
 
562
        char version[2];
 
563
        char uname[32];
 
564
        char gname[32];
 
565
        char devmajor[8];
 
566
        char devminor[8];
 
567
        char atime[12];
 
568
        char ctime[12];
 
569
        char offset[12];
 
570
        char longnames[4];
 
571
        char unused[1];
 
572
        struct {
 
573
                char offset[12];
 
574
                char numbytes[12];
 
575
        } sparse[4];
 
576
        char isextended[1];
 
577
        char realsize[12];
 
578
        char pad[17];
509
579
};
510
580
.Ed
511
581
.Bl -tag -width indent
629
699
sparse blocks as shown here:
630
700
.Bd -literal -offset indent
631
701
struct gnu_sparse_header {
632
 
    struct {
633
 
        char offset[12];
634
 
        char numbytes[12];
635
 
    } sparse[21];
636
 
    char    isextended[1];
637
 
    char    padding[7];
 
702
        struct {
 
703
                char offset[12];
 
704
                char numbytes[12];
 
705
        } sparse[21];
 
706
        char    isextended[1];
 
707
        char    padding[7];
638
708
};
639
709
.Ed
640
710
.It Va realsize
653
723
pax interchange format archives when you specify the
654
724
.Fl -posix
655
725
flag.
656
 
This format uses custom keywords to store sparse file information.
657
 
There have been three iterations of this support, referred to
 
726
This format follows the pax interchange format closely,
 
727
using some
 
728
.Cm SCHILY
 
729
tags and introducing new keywords to store sparse file information.
 
730
There have been three iterations of the sparse file support, referred to
658
731
as
659
732
.Dq 0.0 ,
660
733
.Dq 0.1 ,
729
802
.It
730
803
An additional
731
804
.Cm A
732
 
entry is used to store an ACL for the following regular entry.
 
805
header is used to store an ACL for the following regular entry.
733
806
The body of this entry contains a seven-digit octal number
734
807
followed by a zero byte, followed by the
735
808
textual ACL description.
739
812
.El
740
813
.Ss AIX Tar
741
814
XXX More details needed XXX
 
815
.Pp
 
816
AIX Tar uses a ustar-formatted header with the type
 
817
.Cm A
 
818
for storing coded ACL information.
 
819
Unlike the Solaris format, AIX tar writes this header after the
 
820
regular file body to which it applies.
 
821
The pathname in this header is either
 
822
.Cm NFS4
 
823
or
 
824
.Cm AIXC
 
825
to indicate the type of ACL stored.
 
826
The actual ACL is stored in platform-specific binary format.
742
827
.Ss Mac OS X Tar
743
828
The tar distributed with Apple's Mac OS X stores most regular files
744
 
as two separate entries in the tar archive.
745
 
The two entries have the same name except that the first
 
829
as two separate files in the tar archive.
 
830
The two files have the same name except that the first
746
831
one has
747
832
.Dq ._
748
 
added to the beginning of the name.
749
 
This first entry stores the
750
 
.Dq resource fork
751
 
with additional attributes for the file.
752
 
The Mac OS X
753
 
.Fn CopyFile
754
 
API is used to separate a file on disk into separate
755
 
resource and data streams and to reassemble those separate
756
 
streams when the file is restored to disk.
757
 
.Ss Other Extensions
758
 
One obvious extension to increase the size of files is to
759
 
eliminate the terminating characters from the various
760
 
numeric fields.
761
 
For example, the standard only allows the size field to contain
762
 
11 octal digits, reserving the twelfth byte for a trailing
763
 
NUL character.
764
 
Allowing 12 octal digits allows file sizes up to 64 GB.
765
 
.Pp
766
 
Another extension, utilized by GNU tar, star, and other newer
767
 
.Nm
768
 
implementations, permits binary numbers in the standard numeric fields.
769
 
This is flagged by setting the high bit of the first byte.
770
 
This permits 95-bit values for the length and time fields
771
 
and 63-bit values for the uid, gid, and device numbers.
772
 
GNU tar supports this extension for the
773
 
length, mtime, ctime, and atime fields.
774
 
Joerg Schilling's star program supports this extension for
775
 
all numeric fields.
776
 
Note that this extension is largely obsoleted by the extended attribute
777
 
record provided by the pax interchange format.
778
 
.Pp
779
 
Another early GNU extension allowed base-64 values rather than octal.
780
 
This extension was short-lived and is no longer supported by any
781
 
implementation.
 
833
prepended to the last path element.
 
834
This special file stores an AppleDouble-encoded
 
835
binary blob with additional metadata about the second file,
 
836
including ACL, extended attributes, and resources.
 
837
To recreate the original file on disk, each
 
838
separate file can be extracted and the Mac OS X
 
839
.Fn copyfile
 
840
function can be used to unpack the separate
 
841
metadata file and apply it to th regular file.
 
842
Conversely, the same function provides a
 
843
.Dq pack
 
844
option to encode the extended metadata from
 
845
a file into a separate file whose contents
 
846
can then be put into a tar archive.
 
847
.Pp
 
848
Note that the Apple extended attributes interact
 
849
badly with long filenames.
 
850
Since each file is stored with the full name,
 
851
a separate set of extensions needs to be included
 
852
in the archive for each one, doubling the overhead
 
853
required for files with long names.
 
854
.Ss Summary of tar type codes
 
855
The following list is a condensed summary of the type codes
 
856
used in tar header records generated by different tar implementations.
 
857
More details about specific implementations can be found above:
 
858
.Bl -tag -compact -width XXX
 
859
.It NUL
 
860
Early tar programs stored a zero byte for regular files.
 
861
.It Cm 0
 
862
POSIX standard type code for a regular file.
 
863
.It Cm 1
 
864
POSIX standard type code for a hard link description.
 
865
.It Cm 2
 
866
POSIX standard type code for a symbolic link description.
 
867
.It Cm 3
 
868
POSIX standard type code for a character device node.
 
869
.It Cm 4
 
870
POSIX standard type code for a block device node.
 
871
.It Cm 5
 
872
POSIX standard type code for a directory.
 
873
.It Cm 6
 
874
POSIX standard type code for a FIFO.
 
875
.It Cm 7
 
876
POSIX reserved.
 
877
.It Cm 7
 
878
GNU tar used for pre-allocated files on some systems.
 
879
.It Cm A
 
880
Solaris tar ACL description stored prior to a regular file header.
 
881
.It Cm A
 
882
AIX tar ACL description stored after the file body.
 
883
.It Cm D
 
884
GNU tar directory dump.
 
885
.It Cm K
 
886
GNU tar long linkname for the following header.
 
887
.It Cm L
 
888
GNU tar long pathname for the following header.
 
889
.It Cm M
 
890
GNU tar multivolume marker, indicating the file is a continuation of a file from the previous volume.
 
891
.It Cm N
 
892
GNU tar long filename support.  Deprecated.
 
893
.It Cm S
 
894
GNU tar sparse regular file.
 
895
.It Cm V
 
896
GNU tar tape/volume header name.
 
897
.It Cm X
 
898
Solaris tar general-purpose extension header.
 
899
.It Cm g
 
900
POSIX pax interchange format global extensions.
 
901
.It Cm x
 
902
POSIX pax interchange format per-file extensions.
 
903
.El
782
904
.Sh SEE ALSO
783
905
.Xr ar 1 ,
784
906
.Xr pax 1 ,
809
931
.Nm pdtar
810
932
public-domain implementation (circa 1987) was highly influential
811
933
and formed the basis of
812
 
.Nm GNU tar .
 
934
.Nm GNU tar
 
935
(circa 1988).
813
936
Joerg Shilling's
814
937
.Nm star
815
938
archiver is another open-source (GPL) archiver (originally developed
816
939
circa 1985) which features complete support for pax interchange
817
940
format.
 
941
.Pp
 
942
This documentation was written as part of the
 
943
.Nm libarchive
 
944
and
 
945
.Nm bsdtar
 
946
project by
 
947
.An Tim Kientzle Aq kientzle@FreeBSD.org .