[unix-history] / usr / src / usr.bin / ar / tar.5

.\" Copyright (c) 1983 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)tar.5	5.1 (Berkeley) %G%
.\"
.TH TAR 5  "15 January 1983"
.UC 5
.SH NAME
tar \- tape archive file format
.SH DESCRIPTION
.IR Tar ,
(the tape archive command)
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.
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
blocks (where
.I n
is set by the 
.B b
keyletter on the 
.IR 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
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.
.PP
The header block looks like:
.RS
.PP
.nf
#define TBLOCK	512
#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;
};
.ta \w'#define 'u +\w'SARMAG 'u
.fi
.RE
.LP
.IR Name
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
and
.IR mtime ,
which do not contain the trailing null.
.IR Name
is the name of the file, as specified on the 
.I 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
.I /filename
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
is the file mode, with the top bit masked off.
.IR Uid
and
.IR gid
are the user and group numbers which own the file.
.IR Size
is the size of the file in bytes.  Links and symbolic links are dumped
with this field specified as zero.
.IR Mtime
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
header block.  When calculating the checksum, the 
.IR chksum
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'
if it is a symbolic link.  The name linked-to, if any, is in
.IR linkname,
with a trailing null.
Unused fields of the header are binary zeros (and are included in the
checksum).
.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.
.PP
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
dumped.
Commit	Line	Data
0204d2d0 KM	1	.\" Copyright (c) 1983 Regents of the University of California.
	2	.\" All rights reserved. The Berkeley software License Agreement
	3	.\" specifies the terms and conditions for redistribution.
	4	.\"
	5	.\" @(#)tar.5 5.1 (Berkeley) %G%
	6	.\"
	7	.TH TAR 5 "15 January 1983"
	8	.UC 5
	9	.SH NAME
	10	tar \- tape archive file format
	11	.SH DESCRIPTION
	12	.IR Tar ,
	13	(the tape archive command)
	14	dumps several files into one, in a medium suitable for transportation.
	15	.PP
	16	A ``tar tape'' or file is a series of blocks. Each block is of size TBLOCK.
	17	A file on the tape is represented by a header block which describes
	18	the file, followed by zero or more blocks which give the contents of the
	19	file. At the end of the tape are two blocks filled with binary
	20	zeros, as an end-of-file indicator.
	21	.PP
	22	The blocks are grouped for physical I/O operations. Each group of
	23	.I n
	24	blocks (where
	25	.I n
	26	is set by the
	27	.B b
	28	keyletter on the
	29	.IR tar (1)
	30	command line \(em default is 20 blocks) is written with a single system
	31	call; on nine-track tapes, the result of this write is a single tape
	32	record. The last group is always written at the full size, so blocks after
	33	the two zero blocks contain random data. On reading, the specified or
	34	default group size is used for the
	35	first read, but if that read returns less than a full tape block, the reduced
	36	block size is used for further reads.
	37	.PP
	38	The header block looks like:
	39	.RS
	40	.PP
	41	.nf
	42	#define TBLOCK 512
	43	#define NAMSIZ 100
	44
	45	union hblock {
	46	char dummy[TBLOCK];
	47	struct header {
	48	char name[NAMSIZ];
	49	char mode[8];
	50	char uid[8];
	51	char gid[8];
	52	char size[12];
	53	char mtime[12];
	54	char chksum[8];
	55	char linkflag;
	56	char linkname[NAMSIZ];
	57	} dbuf;
	58	};
	59	.ta \w'#define 'u +\w'SARMAG 'u
	60	.fi
	61	.RE
	62	.LP
	63	.IR Name
	64	is a null-terminated string.
65	The other fields are zero-filled octal numbers in ASCII. Each field
66	(of width w) contains w-2 digits, a space, and a null, except
67	.IR size
68	and
69	.IR mtime ,
70	which do not contain the trailing null.
71	.IR Name
72	is the name of the file, as specified on the
73	.I tar
74	command line. Files dumped because they were in a directory which
75	was named in the command line have the directory name as prefix and
76	.I /filename
77	as suffix.
78	. \"Whatever format was used in the command line
79	. \"will appear here, such as
80	. \".I \&./yellow
81	. \"or
82	. \".IR \&../../brick/./road/.. .
83	. \"To retrieve a file from a tar tape, an exact prefix match must be specified,
84	. \"including all of the directory prefix information used on the command line
85	. \"that dumped the file (if any).
86	.IR Mode
87	is the file mode, with the top bit masked off.
88	.IR Uid
89	and
90	.IR gid
91	are the user and group numbers which own the file.
92	.IR Size
93	is the size of the file in bytes. Links and symbolic links are dumped
94	with this field specified as zero.
95	.IR Mtime
96	is the modification time of the file at the time it was dumped.
97	.IR Chksum
98	is a decimal ASCII value which represents the sum of all the bytes in the
99	header block. When calculating the checksum, the
100	.IR chksum
101	field is treated as if it were all blanks.
102	.IR Linkflag
103	is ASCII `0' if the file is ``normal'' or a special file, ASCII `1'
104	if it is an hard link, and ASCII `2'
105	if it is a symbolic link. The name linked-to, if any, is in
106	.IR linkname,
107	with a trailing null.
108	Unused fields of the header are binary zeros (and are included in the
109	checksum).
110	.PP
111	The first time a given i-node number is dumped, it is dumped as a regular
112	file. The second and subsequent times, it is dumped as a link instead.
113	Upon retrieval, if a link entry is retrieved, but not the file it was
114	linked to, an error message is printed and the tape must be manually
115	re-scanned to retrieve the linked-to file.
116	.PP
117	The encoding of the header is designed to be portable across machines.
118	.SH "SEE ALSO"
119	tar(1)
120	.SH BUGS
121	Names or linknames longer than NAMSIZ produce error reports and cannot be
122	dumped.