contrib/tar/doc/header.texi

   1 /* GNU tar Archive Format description.
   2
   3    Copyright (C) 1988, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
   4    1997, 2000, 2001 Free Software Foundation, Inc.
   5
   6    This program is free software; you can redistribute it and/or modify it
   7    under the terms of the GNU General Public License as published by the
   8    Free Software Foundation; either version 2, or (at your option) any later
   9    version.
  10
  11    This program is distributed in the hope that it will be useful, but
  12    WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
  14    Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License along
  17    with this program; if not, write to the Free Software Foundation, Inc.,
  18    59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
  19
  20 /* If OLDGNU_COMPATIBILITY is not zero, tar produces archives which, by
  21    default, are readable by older versions of GNU tar.  This can be
  22    overriden by using --posix; in this case, POSIXLY_CORRECT in environment
  23    may be set for enforcing stricter conformance.  If OLDGNU_COMPATIBILITY
  24    is zero or undefined, tar will eventually produces archives which, by
  25    default, POSIX compatible; then either using --posix or defining
  26    POSIXLY_CORRECT enforces stricter conformance.
  27
  28    This #define will disappear in a few years.  FP, June 1995.  */
  29 #define OLDGNU_COMPATIBILITY 1
  30
  31 /* tar Header Block, from POSIX 1003.1-1990.  */
  32
  33 /* POSIX header.  */
  34
  35 struct posix_header
  36 @{                               /* byte offset */
  37   char name[100];               /*   0 */
  38   char mode[8];                 /* 100 */
  39   char uid[8];                  /* 108 */
  40   char gid[8];                  /* 116 */
  41   char size[12];                /* 124 */
  42   char mtime[12];               /* 136 */
  43   char chksum[8];               /* 148 */
  44   char typeflag;                /* 156 */
  45   char linkname[100];           /* 157 */
  46   char magic[6];                /* 257 */
  47   char version[2];              /* 263 */
  48   char uname[32];               /* 265 */
  49   char gname[32];               /* 297 */
  50   char devmajor[8];             /* 329 */
  51   char devminor[8];             /* 337 */
  52   char prefix[155];             /* 345 */
  53                                 /* 500 */
  54 @};
  55
  56 #define TMAGIC   "ustar"        /* ustar and a null */
  57 #define TMAGLEN  6
  58 #define TVERSION "00"           /* 00 and no null */
  59 #define TVERSLEN 2
  60
  61 /* Values used in typeflag field.  */
  62 #define REGTYPE  '0'            /* regular file */
  63 #define AREGTYPE '\0'           /* regular file */
  64 #define LNKTYPE  '1'            /* link */
  65 #define SYMTYPE  '2'            /* reserved */
  66 #define CHRTYPE  '3'            /* character special */
  67 #define BLKTYPE  '4'            /* block special */
  68 #define DIRTYPE  '5'            /* directory */
  69 #define FIFOTYPE '6'            /* FIFO special */
  70 #define CONTTYPE '7'            /* reserved */
  71
  72 /* Bits used in the mode field, values in octal.  */
  73 #define TSUID    04000          /* set UID on execution */
  74 #define TSGID    02000          /* set GID on execution */
  75 #define TSVTX    01000          /* reserved */
  76                                 /* file permissions */
  77 #define TUREAD   00400          /* read by owner */
  78 #define TUWRITE  00200          /* write by owner */
  79 #define TUEXEC   00100          /* execute/search by owner */
  80 #define TGREAD   00040          /* read by group */
  81 #define TGWRITE  00020          /* write by group */
  82 #define TGEXEC   00010          /* execute/search by group */
  83 #define TOREAD   00004          /* read by other */
  84 #define TOWRITE  00002          /* write by other */
  85 #define TOEXEC   00001          /* execute/search by other */
  86
  87 /* tar Header Block, GNU extensions.  */
  88
  89 /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for
  90    contiguous files, so maybe disobeying the `reserved' comment in POSIX
  91    header description.  I suspect these were meant to be used this way, and
  92    should not have really been `reserved' in the published standards.  */
  93
  94 /* *BEWARE* *BEWARE* *BEWARE* that the following information is still
  95    boiling, and may change.  Even if the OLDGNU format description should be
  96    accurate, the so-called GNU format is not yet fully decided.  It is
  97    surely meant to use only extensions allowed by POSIX, but the sketch
  98    below repeats some ugliness from the OLDGNU format, which should rather
  99    go away.  Sparse files should be saved in such a way that they do *not*
 100    require two passes at archive creation time.  Huge files get some POSIX
 101    fields to overflow, alternate solutions have to be sought for this.  */
 102
 103 /* Descriptor for a single file hole.  */
 104
 105 struct sparse
 106 @{                               /* byte offset */
 107   char offset[12];              /*   0 */
 108   char numbytes[12];            /*  12 */
 109                                 /*  24 */
 110 @};
 111
 112 /* Sparse files are not supported in POSIX ustar format.  For sparse files
 113    with a POSIX header, a GNU extra header is provided which holds overall
 114    sparse information and a few sparse descriptors.  When an old GNU header
 115    replaces both the POSIX header and the GNU extra header, it holds some
 116    sparse descriptors too.  Whether POSIX or not, if more sparse descriptors
 117    are still needed, they are put into as many successive sparse headers as
 118    necessary.  The following constants tell how many sparse descriptors fit
 119    in each kind of header able to hold them.  */
 120
 121 #define SPARSES_IN_EXTRA_HEADER  16
 122 #define SPARSES_IN_OLDGNU_HEADER 4
 123 #define SPARSES_IN_SPARSE_HEADER 21
 124
 125 /* The GNU extra header contains some information GNU tar needs, but not
 126    foreseen in POSIX header format.  It is only used after a POSIX header
 127    (and never with old GNU headers), and immediately follows this POSIX
 128    header, when typeflag is a letter rather than a digit, so signaling a GNU
 129    extension.  */
 130
 131 struct extra_header
 132 @{                               /* byte offset */
 133   char atime[12];               /*   0 */
 134   char ctime[12];               /*  12 */
 135   char offset[12];              /*  24 */
 136   char realsize[12];            /*  36 */
 137   char longnames[4];            /*  48 */
 138   char unused_pad1[68];         /*  52 */
 139   struct sparse sp[SPARSES_IN_EXTRA_HEADER];
 140                                 /* 120 */
 141   char isextended;              /* 504 */
 142                                 /* 505 */
 143 @};
 144
 145 /* Extension header for sparse files, used immediately after the GNU extra
 146    header, and used only if all sparse information cannot fit into that
 147    extra header.  There might even be many such extension headers, one after
 148    the other, until all sparse information has been recorded.  */
 149
 150 struct sparse_header
 151 @{                               /* byte offset */
 152   struct sparse sp[SPARSES_IN_SPARSE_HEADER];
 153                                 /*   0 */
 154   char isextended;              /* 504 */
 155                                 /* 505 */
 156 @};
 157
 158 /* The old GNU format header conflicts with POSIX format in such a way that
 159    POSIX archives may fool old GNU tar's, and POSIX tar's might well be
 160    fooled by old GNU tar archives.  An old GNU format header uses the space
 161    used by the prefix field in a POSIX header, and cumulates information
 162    normally found in a GNU extra header.  With an old GNU tar header, we
 163    never see any POSIX header nor GNU extra header.  Supplementary sparse
 164    headers are allowed, however.  */
 165
 166 struct oldgnu_header
 167 @{                               /* byte offset */
 168   char unused_pad1[345];        /*   0 */
 169   char atime[12];               /* 345 */
 170   char ctime[12];               /* 357 */
 171   char offset[12];              /* 369 */
 172   char longnames[4];            /* 381 */
 173   char unused_pad2;             /* 385 */
 174   struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
 175                                 /* 386 */
 176   char isextended;              /* 482 */
 177   char realsize[12];            /* 483 */
 178                                 /* 495 */
 179 @};
 180
 181 /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous.
 182    Found in an archive, it indicates an old GNU header format, which will be
 183    hopefully become obsolescent.  With OLDGNU_MAGIC, uname and gname are
 184    valid, though the header is not truly POSIX conforming.  */
 185 #define OLDGNU_MAGIC "ustar  "  /* 7 chars and a null */
 186
 187 /* The standards committee allows only capital A through capital Z for
 188    user-defined expansion.  */
 189
 190 /* This is a dir entry that contains the names of files that were in the
 191    dir at the time the dump was made.  */
 192 #define GNUTYPE_DUMPDIR 'D'
 193
 194 /* Identifies the *next* file on the tape as having a long linkname.  */
 195 #define GNUTYPE_LONGLINK 'K'
 196
 197 /* Identifies the *next* file on the tape as having a long name.  */
 198 #define GNUTYPE_LONGNAME 'L'
 199
 200 /* This is the continuation of a file that began on another volume.  */
 201 #define GNUTYPE_MULTIVOL 'M'
 202
 203 /* For storing filenames that do not fit into the main header.  */
 204 #define GNUTYPE_NAMES 'N'
 205
 206 /* This is for sparse files.  */
 207 #define GNUTYPE_SPARSE 'S'
 208
 209 /* This file is a tape/volume header.  Ignore it on extraction.  */
 210 #define GNUTYPE_VOLHDR 'V'
 211
 212 /* tar Header Block, overall structure.  */
 213
 214 /* tar files are made in basic blocks of this size.  */
 215 #define BLOCKSIZE 512
 216
 217 enum archive_format
 218 @{
 219   DEFAULT_FORMAT,               /* format to be decided later */
 220   V7_FORMAT,                    /* old V7 tar format */
 221   OLDGNU_FORMAT,                /* GNU format as per before tar 1.12 */
 222   POSIX_FORMAT,                 /* restricted, pure POSIX format */
 223   GNU_FORMAT                    /* POSIX format with GNU extensions */
 224 @};
 225
 226 union block
 227 @{
 228   char buffer[BLOCKSIZE];
 229   struct posix_header header;
 230   struct extra_header extra_header;
 231   struct oldgnu_header oldgnu_header;
 232   struct sparse_header sparse_header;
 233 @};
 234
 235 /* End of Format description.  */