]>
Commit | Line | Data |
---|---|---|
3698b958 | 1 | README for GNU tar |
cbde0aa6 | 2 | See the end of file for copying conditions. |
3698b958 | 3 | |
cbde0aa6 | 4 | * Introduction |
3698b958 | 5 | |
3aa399bc | 6 | Please glance through *all* sections of this |
debc4856 PE |
7 | 'README' file before starting configuration. Also make sure you read files |
8 | 'ABOUT-NLS' and 'INSTALL' if you are not familiar with them already. | |
c086e08a | 9 | |
debc4856 PE |
10 | If you got the 'tar' distribution in 'shar' format, time stamps ought to be |
11 | properly restored; do not ignore such complaints at 'unshar' time. | |
ea6fcdf2 | 12 | |
debc4856 | 13 | GNU 'tar' saves many files together into a single tape or disk |
ea6fcdf2 PE |
14 | archive, and can restore individual files from the archive. It includes |
15 | multivolume support, the ability to archive sparse files, automatic archive | |
16 | compression/decompression, remote archives and special features that allow | |
debc4856 PE |
17 | 'tar' to be used for incremental and full backups. This distribution |
18 | also includes 'rmt', the remote tape server. The 'mt' tape drive control | |
19 | program is in the GNU 'cpio' distribution. | |
ea6fcdf2 | 20 | |
debc4856 | 21 | GNU 'tar' is derived from John Gilmore's public domain 'tar'. |
ea6fcdf2 | 22 | |
debc4856 PE |
23 | See file 'ABOUT-NLS' for how to customize this program to your language. |
24 | See file 'COPYING' for copying conditions. | |
25 | See file 'INSTALL' for compilation and installation instructions. | |
debc4856 PE |
26 | See file 'NEWS' for a list of major changes in the current release. |
27 | See file 'THANKS' for a list of contributors. | |
ea6fcdf2 | 28 | |
debc4856 PE |
29 | Besides those configure options documented in files 'INSTALL' and |
30 | 'ABOUT-NLS', an extra option may be accepted after './configure': | |
ea6fcdf2 | 31 | |
cbde0aa6 SP |
32 | * Install |
33 | ||
34 | ** Selecting the default archive format. | |
ea6fcdf2 | 35 | |
c92c357a SP |
36 | The default archive format is GNU, this can be overridden by |
37 | presetting DEFAULT_ARCHIVE_FORMAT while configuring. The allowed | |
cbde0aa6 SP |
38 | values are GNU, V7, OLDGNU, USTAR and POSIX. |
39 | ||
40 | ** Selecting the default archive device | |
c92c357a | 41 | |
debc4856 PE |
42 | The default archive device is now 'stdin' on read and 'stdout' on write. |
43 | The installer can still override this by presetting 'DEFAULT_ARCHIVE' | |
44 | in the environment before configuring (the behavior of '-[0-7]' or | |
45 | '-[0-7]lmh' options in 'tar' are then derived automatically). Similarly, | |
46 | 'DEFAULT_BLOCKING' can be preset to something else than 20. | |
ea6fcdf2 | 47 | |
289687bd SP |
48 | ** Selecting full pathname of the "rmt" binary. |
49 | ||
06bb349c SP |
50 | Previous versions of tar always looked for "rmt" binary in the |
51 | directory "/etc/rmt". However, the "rmt" program included | |
289687bd SP |
52 | in the distribution was installed under "$prefix/libexec/rmt". |
53 | To fix this discrepancy, tar now looks for "$prefix/libexec/rmt". | |
54 | If you do not want this behavior, specify full path name of | |
06bb349c | 55 | "rmt" binary using DEFAULT_RMT_DIR variable, e.g.: |
289687bd | 56 | |
06bb349c SP |
57 | ./configure DEFAULT_RMT_DIR=/etc |
58 | ||
59 | If you already have a copy of "rmt" installed and wish to use it | |
60 | instead of the version supplied with the distribution, use --with-rmt | |
61 | option: | |
62 | ||
63 | ./configure --with-rmt=/etc/rmt | |
64 | ||
65 | This will also disable building the included version of rmt. | |
289687bd SP |
66 | |
67 | ** Installing backup scripts. | |
68 | ||
69 | This version of tar is shipped with the shell scripts for producing | |
70 | incremental backups (dumps) and restoring filesystems from them. | |
71 | The name of the backup script is "backup". The name of the | |
72 | restore script is "restore". They are installed in "$prefix/sbin" | |
73 | directory. | |
74 | ||
75 | Use option --enable-backup-scripts to compile and install these | |
76 | scripts. | |
77 | ||
debc4856 | 78 | ** '--disable-largefile' omits support for large files, even if the |
cbde0aa6 | 79 | operating system supports large files. Typically, large files are |
86e91a5b | 80 | those larger than 2 GB on a 32-bit host. |
ffcddc2e | 81 | |
cbde0aa6 | 82 | * Installation hints |
ea6fcdf2 | 83 | |
debc4856 | 84 | Here are a few hints which might help installing 'tar' on some systems. |
ea6fcdf2 | 85 | |
cbde0aa6 | 86 | ** gzip and bzip2. |
afec2899 PE |
87 | |
88 | GNU tar uses the gzip and bzip2 programs to read and write compressed | |
89 | archives. If you don't have these programs already, you need to | |
90 | install them. Their sources can be found at: | |
91 | ||
92 | ftp://ftp.gnu.org/gnu/gzip/ | |
93 | http://sourceware.cygnus.com/bzip2/ | |
94 | ||
95 | If you see the following symptoms: | |
96 | ||
97 | $ tar -xzf file.tar.gz | |
98 | gzip: stdin: decompression OK, trailing garbage ignored | |
99 | tar: Child returned status 2 | |
100 | ||
101 | then you have encountered a gzip incompatibility that should be fixed | |
ffcddc2e PE |
102 | in gzip test version 1.3, which as of this writing is available at |
103 | <ftp://alpha.gnu.org/gnu/gzip/>. You can work around the | |
104 | incompatibility by using a shell command like | |
debc4856 | 105 | 'gzip -d <file.tar.gz | tar -xzf -'. |
afec2899 | 106 | |
cbde0aa6 | 107 | ** Solaris issues. |
afec2899 | 108 | |
ffcddc2e PE |
109 | GNU tar exercises many features that can cause problems with older GCC |
110 | versions. In particular, GCC 2.8.1 (sparc, -O1 or -O2) is known to | |
111 | miscompile GNU tar. No compiler-related problems have been reported | |
112 | when using GCC 2.95.2 or later. | |
afec2899 PE |
113 | |
114 | Recent versions of Solaris tar sport a new -E option to generate | |
115 | extended headers in an undocumented format. GNU tar does not | |
116 | understand these headers. | |
117 | ||
cbde0aa6 | 118 | ** Static linking. |
ea6fcdf2 | 119 | |
debc4856 PE |
120 | Some platform will, by default, prepare a smaller 'tar' executable |
121 | which depends on shared libraries. Since GNU 'tar' may be used for | |
ea6fcdf2 | 122 | system-level backups and disaster recovery, installers might prefer to |
debc4856 | 123 | force static linking, making a bigger 'tar' executable maybe, but able to |
ea6fcdf2 PE |
124 | work standalone, in situations where shared libraries are not available. |
125 | The way to achieve static linking varies between systems. Set LDFLAGS | |
debc4856 | 126 | to a value from the table below, before configuration (see 'INSTALL'). |
ea6fcdf2 PE |
127 | |
128 | Platform Compiler LDFLAGS | |
129 | ||
130 | (any) Gnu C -static | |
ffcddc2e | 131 | AIX (vendor) -bnso -bI:/lib/syscalls.exp |
ea6fcdf2 PE |
132 | HPUX (vendor) -Wl,-a,archive |
133 | IRIX (vendor) -non_shared | |
134 | OSF (vendor) -non_shared | |
135 | SCO 3.2v5 (vendor) -dn | |
136 | Solaris (vendor) -Bstatic | |
137 | SunOS (vendor) -Bstatic | |
138 | ||
debc4856 | 139 | ** Failed tests 'ignfail.sh' or 'incremen.sh'. |
ea6fcdf2 | 140 | |
0b277662 PE |
141 | In an NFS environment, lack of synchronization between machine clocks |
142 | might create difficulties to any tool comparing dates and file time stamps, | |
debc4856 | 143 | like 'tar' in incremental dumps. This has been a recurrent problem with |
ffcddc2e | 144 | GNU Make for the last few years. We would like a general solution. |
ea6fcdf2 | 145 | |
cbde0aa6 | 146 | ** BSD compatibility matters. |
ea6fcdf2 | 147 | |
debc4856 PE |
148 | Set LIBS to '-lbsd' before configuration (see 'INSTALL') if the linker |
149 | complains about 'bsd_ioctl' (Slackware). Also set CPPFLAGS to | |
150 | '-I/usr/include/bsd' if <sgtty.h> is not found (Slackware). | |
ea6fcdf2 | 151 | |
cbde0aa6 | 152 | ** OPENStep 4.2 swap files |
ea6fcdf2 | 153 | |
bf9a7d3d PE |
154 | Tar cannot read the file /private/vm/swapfile.front (even as root). |
155 | This file is not a real file, but some kind of uncompressed view of | |
156 | the real compressed swap file; there is no reason to back it up, so | |
157 | the simplest workaround is to avoid tarring this file. | |
ea6fcdf2 | 158 | |
cbde0aa6 | 159 | * Special topics |
ea6fcdf2 | 160 | |
debc4856 | 161 | Here are a few special matters about GNU 'tar', not related to build |
ea6fcdf2 PE |
162 | matters. See previous section for such. |
163 | ||
cbde0aa6 | 164 | ** File attributes. |
ea6fcdf2 | 165 | |
debc4856 | 166 | About *security*, it is probable that future releases of 'tar' will have |
0b277662 | 167 | some behavior changed. There are many pending suggestions to choose from. |
debc4856 PE |
168 | Today, extracting an archive not being 'root', 'tar' will restore suid/sgid |
169 | bits on files but owned by the extracting user. 'root' automatically gets | |
170 | a lot of special privileges, '-p' might later become required to get them. | |
ea6fcdf2 | 171 | |
debc4856 | 172 | GNU 'tar' does not properly restore symlink attributes. Various systems |
0b277662 | 173 | implement flavors of symbolic links showing different behavior and |
ea6fcdf2 | 174 | properties. We did not successfully sorted all these out yet. Currently, |
debc4856 | 175 | the 'lchown' call will be used if available, but that's all. |
ea6fcdf2 | 176 | |
cbde0aa6 | 177 | ** POSIX compliance. |
ea6fcdf2 | 178 | |
debc4856 | 179 | GNU 'tar' is able to create archive in the following formats: |
cbde0aa6 SP |
180 | |
181 | *** The format of UNIX version 7 | |
0ab5e64a | 182 | *** POSIX.1-1988 format, also known as "ustar format" |
cbde0aa6 SP |
183 | *** POSIX.1-2001 format, also known as "pax format" |
184 | *** Old GNU format (described below) | |
185 | ||
debc4856 PE |
186 | In addition to those, GNU 'tar' is also able to read archives |
187 | produced by 'star' archiver. | |
cbde0aa6 | 188 | |
debc4856 PE |
189 | A so called 'Old GNU' format is based on an early draft of the |
190 | POSIX 1003.1 'ustar' standard which is different from the final | |
cbde0aa6 SP |
191 | standard. It defines its extensions (such as incremental backups |
192 | and handling of the long file names) in a way incompatible with | |
193 | any existing tar archive format, therefore the use of old GNU | |
0ab5e64a | 194 | format is strongly discouraged. |
cbde0aa6 SP |
195 | |
196 | Please read the file NEWS for more information about POSIX compliance | |
debc4856 | 197 | and new 'tar' features. |
ea6fcdf2 PE |
198 | |
199 | * What's next? | |
200 | ||
289687bd SP |
201 | GNU tar will be merged into GNU paxutils: a project containing |
202 | several utilities related to creating and handling archives in | |
203 | various formats. The project will include tar, cpio and pax | |
204 | utilities. | |
cbde0aa6 SP |
205 | |
206 | * Bug reporting. | |
207 | ||
208 | Send bug reports to <bug-tar@gnu.org>. A bug report should contain | |
209 | an adequate description of the problem, your input, what you expected, | |
210 | what you got, and why this is wrong. Diffs are welcome, but they only | |
211 | describe a solution, from which the problem might be uneasy to infer. | |
212 | If needed, submit actual data files with your report. Small data files | |
213 | are preferred. Big files may sometimes be necessary, but do not send them | |
214 | to the report address; rather take special arrangement with the maintainer. | |
215 | ||
216 | Your feedback will help us to make a better and more portable package. | |
217 | Consider documentation errors as bugs, and report them as such. If you | |
debc4856 | 218 | develop anything pertaining to 'tar' or have suggestions, let us know |
cbde0aa6 SP |
219 | and share your findings by writing to <bug-tar@gnu.org>. |
220 | ||
221 | \f | |
222 | * Copying | |
223 | ||
c6f0ad51 | 224 | Copyright 1990-2024 Free Software Foundation, Inc. |
cbde0aa6 | 225 | |
cd7bdd40 | 226 | This file is part of GNU tar. |
cbde0aa6 | 227 | |
cd7bdd40 PE |
228 | GNU tar is free software; you can redistribute it and/or modify |
229 | it under the terms of the GNU General Public License as published by | |
230 | the Free Software Foundation; either version 3 of the License, or | |
231 | (at your option) any later version. | |
cbde0aa6 | 232 | |
cd7bdd40 PE |
233 | GNU tar is distributed in the hope that it will be useful, |
234 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
235 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
236 | GNU General Public License for more details. | |
cbde0aa6 | 237 | |
cd7bdd40 PE |
238 | You should have received a copy of the GNU General Public License |
239 | along with this program. If not, see <http://www.gnu.org/licenses/>. | |
cbde0aa6 | 240 | |
cd7bdd40 PE |
241 | NOTE ON COPYRIGHT YEARS |
242 | ||
243 | In copyright notices where the copyright holder is the Free Software | |
244 | Foundation, then where a range of years appears, this is an inclusive | |
245 | range that applies to every year in the range. For example: 2005-2008 | |
246 | represents the years 2005, 2006, 2007, and 2008. | |
cbde0aa6 SP |
247 | \f |
248 | Local Variables: | |
249 | mode: outline | |
250 | paragraph-separate: "[ \f]*$" | |
251 | version-control: never | |
252 | End: |