1tar(1) User Commands tar(1)
2
6 tar - create tape archives and add or extract files
7
9 tar c[BDeEFhilnopPqTvw@/[0-7]][bfk][X...] [blocksize]
10 [tarfile] [size] [exclude-file]...
11 {file | −I include-file | −C directory file}...
12 tar r[BDeEFhilnqTvw@/[0-7]][bfk] [blocksize] [tarfile]
15 [size]
16 {file | −I include-file | −C directory file}...
17 tar t[BeFhilnqTv[0-7]][fk][X...] [tarfile] [size]
20 [exclude-file]... {file | −I include-file}...
21 tar u[BDeEFhilnqTvw@/[0-7]][bfk] [blocksize] [tarfile]
24 [size] file...
25 tar x[BeFhilmnopqTvw@/[0-7]][fk][X...] [tarfile] [size]
28 [exclude-file]... [file]...
29
32 The tar command archives and extracts files to and from a single file
33 called a tarfile. A tarfile is usually a magnetic tape, but it can be
34 any file. tar's actions are controlled by the key argument. The key is
35 a string of characters containing exactly one function letter (c, r, t
36 , u, or x) and zero or more function modifiers (letters or digits),
37 depending on the function letter used. The key string contains no SPACE
38 characters. Function modifier arguments are listed on the command line
39 in the same order as their corresponding function modifiers appear in
40 the key string.
41 The −I include-file, −C directory file, and file arguments specify
44 which files or directories are to be archived or extracted. In all
45 cases, appearance of a directory name refers to the files and (recur‐
46 sively) subdirectories of that directory. Arguments appearing within
47 braces ({ }) indicate that one of the arguments must be specified.
48
50 The following operands are supported:
51 −C directory file
53 Performs a chdir (see cd(1)) operation on directory and performs
55 the c (create) or r (replace) operation on file. Use short relative
56 path names for file. If file is ".", archive all files in direc‐
57 tory. This operand enables archiving files from multiple directo‐
58 ries not related by a close common parent.
59 −I include-file
62 Opens include-file containing a list of files, one per line, and
64 treats it as if each file appeared separately on the command line.
65 Be careful of trailing white spaces. Also beware of leading white
66 spaces, since, for each line in the included file, the entire line
67 (apart from the newline) is used to match against the initial
68 string of files to include. In the case where excluded files (see X
69 function modifier) are also specified, they take precedence over
70 all included files. If a file is specified in both the exclude-file
71 and the include-file (or on the command line), it is excluded.
72 file
75 A path name of a regular file or directory to be archived (when the
77 c, r or u functions are specified), extracted (x) or listed (t).
78 When file is the path name of a directory, the action applies to
79 all of the files and (recursively) subdirectories of that direc‐
80 tory.
81 When a file is archived, and the E flag (see Function Modifiers) is
83 not specified, the filename cannot exceed 256 characters. In addi‐
84 tion, it must be possible to split the name between parent direc‐
85 tory names so that the prefix is no longer than 155 characters and
86 the name is no longer than 100 characters. If E is specified, a
87 name of up to PATH_MAX characters can be specified.
88 For example, a file whose basename is longer than 100 characters
90 could not be archived without using the E flag. A file whose direc‐
91 tory portion is 200 characters and whose basename is 50 characters
92 could be archived (without using E) if a slash appears in the
93 directory name somewhere in character positions 151-156.
94 Function Letters
97 The function portion of the key is specified by one of the following
98 letters:
99 c
101 Create. Writing begins at the beginning of the tarfile, instead of
103 at the end.
104 r
107 Replace. The named files are written at the end of the tarfile. A
109 file created with extended headers must be updated with extended
110 headers (see E flag under Function Modifiers). A file created with‐
111 out extended headers cannot be modified with extended headers.
112 t
115 Table of Contents. The names of the specified files are listed each
117 time they occur in the tarfile. If no file argument is specified,
118 the names of all files and any associated extended attributes in
119 the tarfile are listed. With the v function modifier, additional
120 information for the specified files is displayed.
121 u
124 Update. The named files are written at the end of the tarfile if
126 they are not already in the tarfile, or if they have been modified
127 since last written to that tarfile. An update can be rather slow. A
128 tarfile created on a 5.x system cannot be updated on a 4.x system.
129 A file created with extended headers must be updated with extended
130 headers (see E flag under Function Modifiers). A file created with‐
131 out extended headers cannot be modified with extended headers.
132 x
135 Extract or restore. The named files are extracted from the tarfile
137 and written to the directory specified in the tarfile, relative to
138 the current directory. Use the relative path names of files and
139 directories to be extracted.
140 Absolute path names contained in the tar archive are unpacked using
142 the absolute path names, that is, the leading forward slash (/) is
143 not stripped off.
144 If a named file matches a directory whose contents has been written
146 to the tarfile, this directory is recursively extracted. The owner,
147 modification time, and mode are restored (if possible); otherwise,
148 to restore owner, you must be the super-user. Character-special and
149 block-special devices (created by mknod(1M)) can only be extracted
150 by the super-user. If no file argument is specified, the entire
151 content of the tarfile is extracted. If the tarfile contains sev‐
152 eral files with the same name, each file is written to the appro‐
153 priate directory, overwriting the previous one. Filename substitu‐
154 tion wildcards cannot be used for extracting files from the ar‐
155 chive. Rather, use a command of the form:
156 tar xvf ... /dev/rmt/0 `tar tf ... /dev/rmt/0 | \
158 grep 'pattern' `
159 When extracting tapes created with the r or u functions, directory mod‐
165 ification times can not be set correctly. These same functions cannot
166 be used with many tape drives due to tape drive limitations such as the
167 absence of backspace or append capabilities.
168 When using the r, u, or x functions or the X function modifier, the
171 named files must match exactly the corresponding files in the tarfile.
172 For example, to extract ./thisfile, you must specify ./thisfile, and
173 not thisfile. The t function displays how each file was archived.
174 Function Modifiers
176 The characters below can be used in conjunction with the letter that
177 selects the desired function.
178 b blocksize
180 Blocking Factor. Use when reading or writing to raw magnetic ar‐
182 chives (see f below). The blocksize argument specifies the number
183 of 512-byte tape blocks to be included in each read or write opera‐
184 tion performed on the tarfile. The minimum is 1, the default is 20.
185 The maximum value is a function of the amount of memory available
186 and the blocking requirements of the specific tape device involved
187 (see mtio(7I) for details.) The maximum cannot exceed INT_MAX/512
188 (4194303).
189 When a tape archive is being read, its actual blocking factor is
191 automatically detected, provided that it is less than or equal to
192 the nominal blocking factor (the value of the blocksize argument,
193 or the default value if the b modifier is not specified). If the
194 actual blocking factor is greater than the nominal blocking factor,
195 a read error results. See Example 5 in EXAMPLES.
196 B
199 Block. Force tar to perform multiple reads (if necessary) to read
201 exactly enough bytes to fill a block. This function modifier
202 enables tar to work across the Ethernet, since pipes and sockets
203 return partial blocks even when more data is coming. When reading
204 from standard input, "−", this function modifier is selected by
205 default to ensure that tar can recover from short reads.
206 D
209 Data change warnings. Used with c, r, or u function letters.
211 Ignored with t or x function letters. If the size of a file changes
212 while the file is being archived, treat this condition as a warning
213 instead of as an error. A warning message is still written, but the
214 exit status is not affected.
215 e
218 Error. Exit immediately with a positive exit status if any unex‐
220 pected errors occur. The SYSV3 environment variable overrides the
221 default behavior. (See ENVIRONMENT VARIABLES section below.)
222 E
225 Write a tarfile with extended headers. (Used with c, r, or u func‐
227 tion letters. Ignored with t or x function letters.) When a tarfile
228 is written with extended headers, the modification time is main‐
229 tained with a granularity of microseconds rather than seconds. In
230 addition, filenames no longer than PATH_MAX characters that could
231 not be archived without E, and file sizes greater than 8GB, are
232 supported. The E flag is required whenever the larger files and/or
233 files with longer names, or whose UID/GID exceed 2097151, are to be
234 archived, or if time granularity of microseconds is desired.
235 f
238 File. Use the tarfile argument as the name of the tarfile. If f is
240 specified, /etc/default/tar is not searched. If f is omitted, tar
241 uses the device indicated by the TAPE environment variable, if set.
242 Otherwise, tar uses the default values defined in /etc/default/tar.
243 The number matching the archiveN string is used as the output
244 device with the blocking and size specifications from the file. For
245 example,
246 tar -c 2/tmp/*
248 writes the output to the device specified as archive2 in
251 /etc/default/tar.
252 If the name of the tarfile is "−", tar writes to the standard out‐
254 put or reads from the standard input, whichever is appropriate. tar
255 can be used as the head or tail of a pipeline. tar can also be used
256 to move hierarchies with the command:
257 example% cd fromdir; tar cf − .| (cd todir; tar xfBp −)
259 F
264 With one F argument, tar excludes all directories named SCCS and
266 RCS from the tarfile. With two arguments, FF, tar excludes all
267 directories named SCCS and RCS, all files with .o as their suffix,
268 and all files named errs, core, and a.out. The SYSV3 environment
269 variable overrides the default behavior. (See ENVIRONMENT VARIABLES
270 section below.)
271 h
274 Follow symbolic links as if they were normal files or directories.
276 Normally, tar does not follow symbolic links.
277 i
280 Ignore directory checksum errors.
282 k size
285 Requires tar to use the size argument as the size of an archive in
287 kilobytes. This is useful when the archive is intended for a fixed
288 size device such as floppy disks. Large files are then split across
289 volumes if they do not fit in the specified size.
290 l
293 Link. Output error message if unable to resolve all links to the
295 files being archived. If l is not specified, no error messages are
296 printed.
297 m
300 Modify. The modification time of the file is the time of extrac‐
302 tion. This function modifier is valid only with the x function.
303 n
306 The file being read is a non-tape device. Reading of the archive is
308 faster since tar can randomly seek around the archive.
309 o
312 Ownership. Assign to extracted files the user and group identifiers
314 of the user running the program, rather than those on tarfile. This
315 is the default behavior for users other than root. If the o func‐
316 tion modifier is not set and the user is root, the extracted files
317 takes on the group and user identifiers of the files on tarfile
318 (see chown(1) for more information). The o function modifier is
319 only valid with the x function.
320 p
323 Restore the named files to their original modes, and ACLs if appli‐
325 cable, ignoring the present umask(1). This is the default behavior
326 if invoked as super-user with the x function letter specified. If
327 super-user, SETUID, and sticky information are also extracted, and
328 files are restored with their original owners and permissions,
329 rather than owned by root. When this function modifier is used with
330 the c function, ACLs are created in the tarfile along with other
331 information. Errors occur when a tarfile with ACLs is extracted by
332 previous versions of tar.
333 P
336 Suppress the addition of a trailing "/" on directory entries in the
338 archive.
339 q
342 Stop after extracting the first occurrence of the named file. tar
344 normally continues reading the archive after finding an occurrence
345 of a file.
346 T
349 This modifier is only available if the system is configured with
351 Trusted Extensions.
352 When this modifier is used with the function letter c, r, or u for
354 creating, replacing or updating a tarfile, the sensitivity label
355 associated with each archived file and directory is stored in the
356 tarfile.
357 Specifying T implies the function modifier p.
359 When used with the function letter x for extracting a tarfile, the
361 tar program verifies that the file's sensitivity label specified in
362 the archive equals the sensitivity label of the destination direc‐
363 tory. If not, the file is not restored. This operation must be
364 invoked from the global zone. If the archived file has a relative
365 pathname, it is restored to the corresponding directory with the
366 same label, if available. This is done by prepending to the current
367 destination directory the root pathname of the zone whose label
368 equals the file. If no such zone exists, the file is not restored.
369 Limited support is provided for extracting labeled archives from
371 Trusted Solaris 8. Only sensitivity labels, and multi-level direc‐
372 tory specifications are interpreted. Privilege specifications and
373 audit attribute flags are silently ignored. Multilevel directory
374 specifications including symbolic links to single level directories
375 are are mapped into zone-relative pathnames if a zone with the same
376 label is available. This support is intended to facilitate migra‐
377 tion of home directories. Architectural differences preclude the
378 extraction of arbitrarily labeled files from Trusted Solaris 8 into
379 identical pathnames in Trusted Extensions. Files cannot be
380 extracted unless their archived label matches the destination
381 label.
382 v
385 Verbose. Output the name of each file preceded by the function let‐
387 ter. With the t function, v provides additional information about
388 the tarfile entries. The listing is similar to the format produced
389 by the -l option of the ls(1) command.
390 w
393 What. Output the action to be taken and the name of the file, then
395 await the user's confirmation. If the response is affirmative, the
396 action is performed; otherwise, the action is not performed. This
397 function modifier cannot be used with the t function.
398 X
401 Exclude. Use the exclude-file argument as a file containing a list
403 of relative path names for files (or directories) to be excluded
404 from the tarfile when using the functions c, x, or t. Be careful of
405 trailing white spaces. Also beware of leading white spaces, since,
406 for each line in the excluded file, the entire line (apart from the
407 newline) is used to match against the initial string of files to
408 exclude. Lines in the exclude file are matched exactly, so an entry
409 like "/var" does not exclude the /var directory if tar is backing
410 up relative pathnames. The entry should read "./var" under these
411 circumstances. The tar command does not expand shell metacharacters
412 in the exclude file, so specifying entries like "*.o" does not have
413 the effect of excluding all files with names suffixed with ".o". If
414 a complex list of files is to be excluded, the exclude file should
415 be generated by some means such as the find(1) command with appro‐
416 priate conditions.
417 Multiple X arguments can be used, with one exclude-file per argu‐
419 ment. In the case where included files (see −I include-file oper‐
420 and) are also specified, the excluded files take precedence over
421 all included files. If a file is specified in both the exclude-file
422 and the include-file (or on the command line), it is excluded.
423 @
426 Include extended attributes in archive. By default, tar does not
428 place extended attributes in the archive. With this flag, tar looks
429 for extended attributes on the files to be placed in the archive
430 and add them to the archive. Extended attributes go in the archive
431 as special files with a special type label. When this modifier is
432 used with the x function, extended attributes are extracted from
433 the tape along with the normal file data. Extended attribute files
434 can only be extracted from an archive as part of a normal file
435 extract. Attempts to explicitly extract attribute records are
436 ignored.
437 /
440 Include extended system attributes in archive. By default, tar does
442 not place extended system attributes in the archive. With this
443 flag, tar looks for extended system attributes on the files to be
444 placed in the archive and adds them to the archive. Extended system
445 attributes go in the archive as special files with a special type
446 label. When this modifier is used with the x function, extended
447 system attributes are extracted from the tape along with the normal
448 file data. Extended system attribute files can only be extracted
449 from an archive as part of a normal file extract. Attempts to
450 explicitly extract attribute records are ignored.
451 [0-7]
454 Select an alternative drive on which the tape is mounted. The
456 default entries are specified in /etc/default/tar. If no digit or f
457 function modifier is specified, the entry in /etc/default/tar with
458 digit "0" is the default.
459
462 See largefile(5) for the description of the behavior of tar when
463 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
464 The automatic determination of the actual blocking factor can be fooled
467 when reading from a pipe or a socket (see the B function modifier
468 below).
469 1/4" streaming tape has an inherent blocking factor of one 512-byte
472 block. It can be read or written using any blocking factor.
473 This function modifier works for archives on disk files and block spe‐
476 cial devices, among others, but is intended principally for tape
477 devices.
478 For information on tar header format, see archives.h(3HEAD).
481
483 Example 1 Creating an archive of your home directory
484 The following is an example using tar to create an archive of your home
487 directory on a tape mounted on drive /dev/rmt/0:
488 example% cd
491 example% tar cvf /dev/rmt/0 .
492 messages from tar
493 The c function letter means create the archive. The v function modifier
498 outputs messages explaining what tar is doing. The f function modifier
499 indicates that the tarfile is being specified (/dev/rmt/0 in this exam‐
500 ple). The dot (.) at the end of the command line indicates the current
501 directory and is the argument of the f function modifier.
502 Display the table of contents of the tarfile with the following com‐
506 mand:
507 example% tar tvf /dev/rmt/0
510 The output is similar to the following for the POSIX locale:
515 rw−r−−r−− 1677/40 2123 Nov 7 18:15 1985 ./test.c
518 ...
519 example%
520 The columns have the following meanings:
525 o column 1 is the access permissions to ./test.c
528 o column 2 is the user-id/group-id of ./test.c
530 o column 3 is the size of ./test.c in bytes
532 o column 4 is the modification date of ./test.c. When the
534 LC_TIME category is not set to the POSIX locale, a different
535 format and date order field can be used.
536 o column 5 is the name of ./test.c
538 To extract files from the archive:
541 example% tar xvf /dev/rmt/0
544 messages from tar
545 example%
546 If there are multiple archive files on a tape, each is separated from
551 the following one by an EOF marker. To have tar read the first and sec‐
552 ond archives from a tape with multiple archives on it, the non-rewind‐
553 ing version of the tape device name must be used with the f function
554 modifier, as follows:
555 example% tar xvfp /dev/rmt/0n read first archive from tape
558 messages from tar
559 example% tar xvfp /dev/rmt/0n read second archive from tape
560 messages from tar
561 example%
562 Notice that in some earlier releases, the above scenario did not work
567 correctly, and intervention with mt(1) between tar invocations was nec‐
568 essary. To emulate the old behavior, use the non-rewind device name
569 containing the letter b for BSD behavior. See the Close Operations sec‐
570 tion of the mtio(7I) manual page.
571 Example 2 Archiving files from /usr/include and from /etc to default
574 tape drive 0
575 To archive files from /usr/include and from /etc to default tape drive
578 0:
579 example% tar c -C /usr include -C /etc .
582 The table of contents from the resulting tarfile would produce output
587 like the following:
588 include/
591 include/a.out.h
592 and all the other files in /usr/include ...
593 ./chown and all the other files in /etc
594 To extract all files in the include directory:
599 example% tar xv include
602 x include/, 0 bytes, 0 tape blocks \
603 and all files under include ...
604 Example 3 Transferring files across the network
608 The following is an example using tar to transfer files across the net‐
611 work. First, here is how to archive files from the local machine (exam‐
612 ple) to a tape on a remote system (host):
613 example% tar cvfb − 20 files| \
616 rsh host dd of=/dev/rmt/0 obs=20b
617 messages from tar
618 example%
619 In the example above, we are creating a tarfile with the c key letter,
624 asking for verbose output from tar with the v function modifier, speci‐
625 fying the name of the output tarfile using the f function modifier (the
626 standard output is where the tarfile appears, as indicated by the `−'
627 sign), and specifying the blocksize (20) with the b function modifier.
628 If you want to change the blocksize, you must change the blocksize
629 arguments both on the tar command and on the dd command.
630 Example 4 Retrieving files from a tape on the remote system back to the
633 local system
634 The following is an example that uses tar to retrieve files from a tape
637 on the remote system back to the local system:
638 example% rsh -n host dd if=/dev/rmt/0 bs=20b | \
641 tar xvBfb − 20 files
642 messages from tar
643 example%
644 In the example above, we are extracting from the tarfile with the x key
649 letter, asking for verbose output from tar with the v function modi‐
650 fier, telling tar it is reading from a pipe with the B function modi‐
651 fier, specifying the name of the input tarfile using the f function
652 modifier (the standard input is where the tarfile appears, as indicated
653 by the "−" sign), and specifying the blocksize (20) with the b function
654 modifier.
655 Example 5 Creating an archive of the home directory
658 The following example creates an archive of the home directory on
661 /dev/rmt/0 with an actual blocking factor of 19:
662 example% tar cvfb /dev/rmt/0 19 $HOME
665 To recognize this archive's actual blocking factor without using the b
670 function modifier:
671 example% tar tvf /dev/rmt/0
674 tar: blocksize = 19
675 ...
676 To recognize this archive's actual blocking factor using a larger nomi‐
681 nal blocking factor:
682 example% tar tvf /dev/rmt/0 30
685 tar: blocksize = 19
686 ...
687 Attempt to recognize this archive's actual blocking factor using a nom‐
692 inal blocking factor that is too small:
693 example% tar tvf /dev/rmt/0 10
696 tar: tape read error
697
701 SYSV3
702 This variable is used to override the default behavior of tar, pro‐
704 vide compatibility with INTERACTIVE UNIX Systems and SCO UNIX
705 installation scripts, and should not be used in new scripts. (It is
706 intended for compatibility purposes only.) When set, the following
707 function modifiers behave differently:
708 F filename
710 Uses filename to obtain a list of command line switches and
712 files on which to operate.
713 e
716 Prevents files from being split across volumes. If there is
718 insufficient room on one volume, tar prompts for a new volume.
719 If the file does not fit on the new volume, tar exits with an
720 error.
721 See environ(5) for descriptions of the following environment variables
726 that affect the execution of tar: LC_COLLATE, LC_CTYPE, LC_MESSAGES,
727 LC_TIME, TZ, and NLSPATH.
728 Affirmative responses are processed using the extended regular expres‐
731 sion defined for the yesexpr keyword in the LC_MESSAGES category of the
732 user's locale. The locale specified in the LC_COLLATE category defines
733 the behavior of ranges, equivalence classes, and multi-character col‐
734 lating elements used in the expression defined for yesexpr. The locale
735 specified in LC_CTYPE determines the locale for interpretation of
736 sequences of bytes of text data a characters, the behavior of character
737 classes used in the expression defined for the yesexpr. See locale(5).
738
740 The following exit values are returned:
741 0
743 Successful completion.
745 >0
748 An error occurred.
750
753 /dev/rmt/[0-7][b][n]
754 /dev/rmt/[0-7]l[b][n]
759 /dev/rmt/[0-7]m[b][n]
764 /dev/rmt/[0-7]h[b][n]
769 /dev/rmt/[0-7]u[b][n]
774 /dev/rmt/[0-7]c[b][n]
779 /etc/default/tar
784 Settings might look like this:
786 archive0=/dev/rmt/0
787 archive1=/dev/rmt/0n
788 archive2=/dev/rmt/1
789 archive3=/dev/rmt/1n
790 archive4=/dev/rmt/0
791 archive5=/dev/rmt/0n
792 archive6=/dev/rmt/1
793 archive7=/dev/rmt/1n
794 /tmp/tar*
797
802 See attributes(5) for descriptions of the following attributes:
803 ┌─────────────────────────────┬─────────────────────────────┐
808 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
809 ├─────────────────────────────┼─────────────────────────────┤
810 │Availability │SUNWcsu │
811 ├─────────────────────────────┼─────────────────────────────┤
812 │CSI │Enabled │
813 ├─────────────────────────────┼─────────────────────────────┤
814 │Interface Stability │Committed │
815 └─────────────────────────────┴─────────────────────────────┘
816
818 ar(1), basename(1), cd(1), chown(1), cpio(1), csh(1), dirname(1),
819 find(1), ls(1), mt(1), pax(1), setfacl(1), umask(1), mknod(1M), ar‐
820 chives.h(3HEAD), attributes(5), environ(5), fsattr(5), largefile(5),
821 mtio(7I)
822
824 Diagnostic messages are output for bad key characters and tape
825 read/write errors, and for insufficient memory to hold the link tables.
826
828 There is no way to access the n-th occurrence of a file.
829 Tape errors are handled ungracefully.
832 The tar archive format allows UIDs and GIDs up to 2097151 to be stored
835 in the archive header. Files with UIDs and GIDs greater than this value
836 is archived with the UID and GID of 60001.
837 If an archive is created that contains files whose names were created
840 by processes running in multiple locales, a single locale that uses a
841 full 8-bit codeset (for example, the en_US locale) should be used both
842 to create the archive and to extract files from the archive.
843 Neither the r function letter nor the u function letter can be used
846 with quarter-inch archive tapes, since these tape drives cannot
847 backspace.
848 Since tar has no options, the standard "−−" argument that is normally
851 used in other utilities to terminate recognition of options is not
852 needed. If used, it is recognized only as the first argument and is
853 ignored.
854 Since −C directory file and −I include-file are multi-argument oper‐
857 ands, any of the following methods can be used to archive or extract a
858 file named −C or −I:
859 1. Specify them using file operands containing a / character on
861 the command line (such as /home/joe/−C or ./−I).
862 2. Include them in an include file with −I include-file.
864 3. Specify the directory in which the file resides:
866 -C directory -C
868 or
871 -C directory -I
873 4. Specify the entire directory in which the file resides:
877 -C directory .
879SunOS 5.11 26 Oct 2007 tar(1)