BSD 4_4 release

[unix-history] / usr / src / old / tar / tarformat.5

diff --git a/usr/src/old/tar/tarformat.5 b/usr/src/old/tar/tarformat.5
index 628bb85..65744ab 100644 (file)
--- a/usr/src/old/tar/tarformat.5
+++ b/usr/src/old/tar/tarformat.5
@@ -1,32 +1,66 @@
-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1983, 1991 Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)tarformat.5 5.1 (Berkeley) %G%
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.

 .\"
 .\"

-.TH TAR 5  "15 January 1983"
-.UC 5
-.SH NAME
-tar \- tape archive file format
-.SH DESCRIPTION
-.IR Tar ,
-(the tape archive command)
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)tarformat.5        6.4 (Berkeley) 5/10/91
+.\"
+.Dd May 10, 1991
+.Dt TAR 5
+.Os BSD 4.2
+.Sh NAME
+.Nm tar
+.Nd tape archive file format
+.Sh DESCRIPTION
+The
+.Nm tar
+tape archive command

 dumps several files into one, in a medium suitable for transportation.
 dumps several files into one, in a medium suitable for transportation.

-.PP
-A ``tar tape'' or file is a series of blocks.  Each block is of size TBLOCK.
+.Pp
+A ``tar tape'' or file is a series of blocks.  Each block is of size
+.Dv TBLOCK .

 A file on the tape is represented by a header block which describes
 the file, followed by zero or more blocks which give the contents of the
 file.  At the end of the tape are two blocks filled with binary
 zeros, as an end-of-file indicator.  
 A file on the tape is represented by a header block which describes
 the file, followed by zero or more blocks which give the contents of the
 file.  At the end of the tape are two blocks filled with binary
 zeros, as an end-of-file indicator.  

-.PP
-The blocks are grouped for physical I/O operations.  Each group of
-.I n
+.Pp
+The blocks are grouped for physical
+.Tn I/O
+operations.  Each group of
+.Ar n
+functions

 blocks (where
 blocks (where

-.I n
+.Ar n

 is set by the 
 is set by the 

-.B b
+.Cm b

 keyletter on the 
 keyletter on the 

-.IR tar (1)
+.Xr tar 1

 command line \(em default is 20 blocks) is written with a single system
 call; on nine-track tapes, the result of this write is a single tape
 record.  The last group is always written at the full size, so blocks after
 command line \(em default is 20 blocks) is written with a single system
 call; on nine-track tapes, the result of this write is a single tape
 record.  The last group is always written at the full size, so blocks after


@@ -34,89 +68,100 @@ the two zero blocks contain random data.  On reading, the specified or
 default group size is used for the
 first read, but if that read returns less than a full tape block, the reduced
 block size is used for further reads.
 default group size is used for the
 first read, but if that read returns less than a full tape block, the reduced
 block size is used for further reads.

-.PP
+.Pp

 The header block looks like:
 The header block looks like:

-.RS
-.PP
-.nf
+.Bd -literal -offset indent

 #define TBLOCK 512
 #define TBLOCK 512

+#define NBLOCK 20

 #define NAMSIZ 100
 
 union hblock {
 #define NAMSIZ 100
 
 union hblock {

-       char dummy[TBLOCK];
-       struct header {
-               char name[NAMSIZ];
-               char mode[8];
-               char uid[8];
-               char gid[8];
-               char size[12];
-               char mtime[12];
-               char chksum[8];
-               char linkflag;
-               char linkname[NAMSIZ];
-       } dbuf;
+        char dummy[TBLOCK];
+        struct header {
+                char name[NAMSIZ];
+                char mode[8];
+                char uid[8];
+                char gid[8];
+                char size[12];
+                char mtime[12];
+                char chksum[8];
+                char linkflag;
+                char linkname[NAMSIZ];
+        } dbuf;

 };
 };

-.ta \w'#define 'u +\w'SARMAG 'u
-.fi
-.RE
-.LP
-.IR Name
+.Ed
+.Pp
+The
+.Fa name
+field

 is a null-terminated string.
 is a null-terminated string.

-The other fields are zero-filled octal numbers in ASCII.  Each field
-(of width w) contains w-2 digits, a space, and a null, except
-.IR size
+The other fields are zero-filled octal numbers in
+.Tn ASCII . 
+Each field
+(of width w) contains w\-2 digits, a space, and a null, except
+.Xr size

 and
 and

-.IR mtime ,
-which do not contain the trailing null.
-.IR Name
+.Fa mtime ,
+which do not contain the trailing null and
+.Fa chksum
+which has a null followed by a space.
+.Fa Name

 is the name of the file, as specified on the 
 is the name of the file, as specified on the 

-.I tar
-command line.  Files dumped because they were in a directory which
+.Nm tar
+command line.
+Files dumped because they were in a directory which

 was named in the command line have the directory name as prefix and
 was named in the command line have the directory name as prefix and

-.I /filename
+.Pa /filename

 as suffix.
 as suffix.

-.  \"Whatever format was used in the command line
-.  \"will appear here, such as
-.  \".I \&./yellow
-.  \"or
-.  \".IR \&../../brick/./road/.. .
-.  \"To retrieve a file from a tar tape, an exact prefix match must be specified,
-.  \"including all of the directory prefix information used on the command line
-.  \"that dumped the file (if any).
-.IR Mode
+.Fa Mode

 is the file mode, with the top bit masked off.
 is the file mode, with the top bit masked off.

-.IR Uid
+.Fa Uid

 and
 and

-.IR gid
+.Fa gid

 are the user and group numbers which own the file.
 are the user and group numbers which own the file.

-.IR Size
+.Fa Size

 is the size of the file in bytes.  Links and symbolic links are dumped
 with this field specified as zero.
 is the size of the file in bytes.  Links and symbolic links are dumped
 with this field specified as zero.

-.IR Mtime
+.Fa Mtime

 is the modification time of the file at the time it was dumped.
 is the modification time of the file at the time it was dumped.

-.IR Chksum
-is a decimal ASCII value which represents the sum of all the bytes in the
+.Fa Chksum
+is an octal
+.Tn ASCII
+value which represents the sum of all the bytes in the

 header block.  When calculating the checksum, the 
 header block.  When calculating the checksum, the 

-.IR chksum
+.Fa chksum

 field is treated as if it were all blanks.
 field is treated as if it were all blanks.

-.IR Linkflag
-is ASCII `0' if the file is ``normal'' or a special file, ASCII `1'
-if it is an hard link, and ASCII `2'
+.Fa Linkflag
+is
+.Dv NULL
+if the file is ``normal'' or a special file,
+.Tn ASCII
+`1'
+if it is an hard link, and
+.Tn ASCII
+`2'

 if it is a symbolic link.  The name linked-to, if any, is in
 if it is a symbolic link.  The name linked-to, if any, is in

-.IR linkname,
+.Fa linkname ,

 with a trailing null.
 Unused fields of the header are binary zeros (and are included in the
 checksum).
 with a trailing null.
 Unused fields of the header are binary zeros (and are included in the
 checksum).

-.PP
+.Pp

 The first time a given i-node number is dumped, it is dumped as a regular
 file.  The second and subsequent times, it is dumped as a link instead.
 Upon retrieval, if a link entry is retrieved, but not the file it was
 linked to, an error message is printed and the tape must be manually
 re-scanned to retrieve the linked-to file.
 The first time a given i-node number is dumped, it is dumped as a regular
 file.  The second and subsequent times, it is dumped as a link instead.
 Upon retrieval, if a link entry is retrieved, but not the file it was
 linked to, an error message is printed and the tape must be manually
 re-scanned to retrieve the linked-to file.

-.PP
+.Pp

 The encoding of the header is designed to be portable across machines.
 The encoding of the header is designed to be portable across machines.

-.SH "SEE ALSO"
-tar(1)
-.SH BUGS
-Names or linknames longer than NAMSIZ produce error reports and cannot be
+.Sh SEE ALSO
+.Xr tar 1
+.Sh BUGS
+Names or linknames longer than
+.Dv NAMSIZ
+produce error reports and cannot be

 dumped.
 dumped.

+.Sh HISTORY
+The
+.Nm
+file format manual appeared in
+.Bx 4.2 .