001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019 package org.apache.commons.compress.archivers.tar;
020
021 import java.io.File;
022 import java.util.Date;
023 import java.util.Locale;
024
025 import org.apache.commons.compress.archivers.ArchiveEntry;
026
027 /**
028 * This class represents an entry in a Tar archive. It consists
029 * of the entry's header, as well as the entry's File. Entries
030 * can be instantiated in one of three ways, depending on how
031 * they are to be used.
032 * <p>
033 * TarEntries that are created from the header bytes read from
034 * an archive are instantiated with the TarEntry( byte[] )
035 * constructor. These entries will be used when extracting from
036 * or listing the contents of an archive. These entries have their
037 * header filled in using the header bytes. They also set the File
038 * to null, since they reference an archive entry not a file.
039 * <p>
040 * TarEntries that are created from Files that are to be written
041 * into an archive are instantiated with the TarEntry( File )
042 * constructor. These entries have their header filled in using
043 * the File's information. They also keep a reference to the File
044 * for convenience when writing entries.
045 * <p>
046 * Finally, TarEntries can be constructed from nothing but a name.
047 * This allows the programmer to construct the entry by hand, for
048 * instance when only an InputStream is available for writing to
049 * the archive, and the header information is constructed from
050 * other information. In this case the header fields are set to
051 * defaults and the File is set to null.
052 *
053 * <p>
054 * The C structure for a Tar Entry's header is:
055 * <pre>
056 * struct header {
057 * char name[100]; // TarConstants.NAMELEN - offset 0
058 * char mode[8]; // TarConstants.MODELEN - offset 100
059 * char uid[8]; // TarConstants.UIDLEN - offset 108
060 * char gid[8]; // TarConstants.GIDLEN - offset 116
061 * char size[12]; // TarConstants.SIZELEN - offset 124
062 * char mtime[12]; // TarConstants.MODTIMELEN - offset 136
063 * char chksum[8]; // TarConstants.CHKSUMLEN - offset 148
064 * char linkflag[1]; // - offset 156
065 * char linkname[100]; // TarConstants.NAMELEN - offset 157
066 * The following fields are only present in new-style POSIX tar archives:
067 * char magic[6]; // TarConstants.MAGICLEN - offset 257
068 * char version[2]; // TarConstants.VERSIONLEN - offset 263
069 * char uname[32]; // TarConstants.UNAMELEN - offset 265
070 * char gname[32]; // TarConstants.GNAMELEN - offset 297
071 * char devmajor[8]; // TarConstants.DEVLEN - offset 329
072 * char devminor[8]; // TarConstants.DEVLEN - offset 337
073 * char prefix[155]; // TarConstants.PREFIXLEN - offset 345
074 * // Used if "name" field is not long enough to hold the path
075 * char pad[12]; // NULs - offset 500
076 * } header;
077 * All unused bytes are set to null.
078 * New-style GNU tar files are slightly different from the above.
079 * </pre>
080 *
081 * @NotThreadSafe
082 */
083
084 public class TarArchiveEntry implements TarConstants, ArchiveEntry {
085 /** The entry's name. */
086 private String name;
087
088 /** The entry's permission mode. */
089 private int mode;
090
091 /** The entry's user id. */
092 private int userId;
093
094 /** The entry's group id. */
095 private int groupId;
096
097 /** The entry's size. */
098 private long size;
099
100 /** The entry's modification time. */
101 private long modTime;
102
103 /** The entry's link flag. */
104 private byte linkFlag;
105
106 /** The entry's link name. */
107 private String linkName;
108
109 /** The entry's magic tag. */
110 private String magic;
111 /** The version of the format */
112 private String version;
113
114 /** The entry's user name. */
115 private String userName;
116
117 /** The entry's group name. */
118 private String groupName;
119
120 /** The entry's major device number. */
121 private int devMajor;
122
123 /** The entry's minor device number. */
124 private int devMinor;
125
126 /** The entry's file reference */
127 private File file;
128
129 /** Maximum length of a user's name in the tar file */
130 public static final int MAX_NAMELEN = 31;
131
132 /** Default permissions bits for directories */
133 public static final int DEFAULT_DIR_MODE = 040755;
134
135 /** Default permissions bits for files */
136 public static final int DEFAULT_FILE_MODE = 0100644;
137
138 /** Convert millis to seconds */
139 public static final int MILLIS_PER_SECOND = 1000;
140
141 /**
142 * Construct an empty entry and prepares the header values.
143 */
144 private TarArchiveEntry () {
145 this.magic = MAGIC_POSIX;
146 this.version = VERSION_POSIX;
147 this.name = "";
148 this.linkName = "";
149
150 String user = System.getProperty("user.name", "");
151
152 if (user.length() > MAX_NAMELEN) {
153 user = user.substring(0, MAX_NAMELEN);
154 }
155
156 this.userId = 0;
157 this.groupId = 0;
158 this.userName = user;
159 this.groupName = "";
160 this.file = null;
161 }
162
163 /**
164 * Construct an entry with only a name. This allows the programmer
165 * to construct the entry's header "by hand". File is set to null.
166 *
167 * @param name the entry name
168 */
169 public TarArchiveEntry(String name) {
170 this();
171
172 name = normalizeFileName(name);
173 boolean isDir = name.endsWith("/");
174
175 this.devMajor = 0;
176 this.devMinor = 0;
177 this.name = name;
178 this.mode = isDir ? DEFAULT_DIR_MODE : DEFAULT_FILE_MODE;
179 this.linkFlag = isDir ? LF_DIR : LF_NORMAL;
180 this.userId = 0;
181 this.groupId = 0;
182 this.size = 0;
183 this.modTime = (new Date()).getTime() / MILLIS_PER_SECOND;
184 this.linkName = "";
185 this.userName = "";
186 this.groupName = "";
187 this.devMajor = 0;
188 this.devMinor = 0;
189
190 }
191
192 /**
193 * Construct an entry with a name and a link flag.
194 *
195 * @param name the entry name
196 * @param linkFlag the entry link flag.
197 */
198 public TarArchiveEntry(String name, byte linkFlag) {
199 this(name);
200 this.linkFlag = linkFlag;
201 }
202
203 /**
204 * Construct an entry for a file. File is set to file, and the
205 * header is constructed from information from the file.
206 * The name is set from the normalized file path.
207 *
208 * @param file The file that the entry represents.
209 */
210 public TarArchiveEntry(File file) {
211 this(file, normalizeFileName(file.getPath()));
212 }
213
214 /**
215 * Construct an entry for a file. File is set to file, and the
216 * header is constructed from information from the file.
217 *
218 * @param file The file that the entry represents.
219 * @param fileName the name to be used for the entry.
220 */
221 public TarArchiveEntry(File file, String fileName) {
222 this();
223
224 this.file = file;
225
226 this.linkName = "";
227
228 if (file.isDirectory()) {
229 this.mode = DEFAULT_DIR_MODE;
230 this.linkFlag = LF_DIR;
231
232 int nameLength = fileName.length();
233 if (nameLength == 0 || fileName.charAt(nameLength - 1) != '/') {
234 this.name = fileName + "/";
235 } else {
236 this.name = fileName;
237 }
238 this.size = 0;
239 } else {
240 this.mode = DEFAULT_FILE_MODE;
241 this.linkFlag = LF_NORMAL;
242 this.size = file.length();
243 this.name = fileName;
244 }
245
246 this.modTime = file.lastModified() / MILLIS_PER_SECOND;
247 this.devMajor = 0;
248 this.devMinor = 0;
249 }
250
251 /**
252 * Construct an entry from an archive's header bytes. File is set
253 * to null.
254 *
255 * @param headerBuf The header bytes from a tar archive entry.
256 */
257 public TarArchiveEntry(byte[] headerBuf) {
258 this();
259 parseTarHeader(headerBuf);
260 }
261
262 /**
263 * Determine if the two entries are equal. Equality is determined
264 * by the header names being equal.
265 *
266 * @param it Entry to be checked for equality.
267 * @return True if the entries are equal.
268 */
269 public boolean equals(TarArchiveEntry it) {
270 return getName().equals(it.getName());
271 }
272
273 /**
274 * Determine if the two entries are equal. Equality is determined
275 * by the header names being equal.
276 *
277 * @param it Entry to be checked for equality.
278 * @return True if the entries are equal.
279 */
280 public boolean equals(Object it) {
281 if (it == null || getClass() != it.getClass()) {
282 return false;
283 }
284 return equals((TarArchiveEntry) it);
285 }
286
287 /**
288 * Hashcodes are based on entry names.
289 *
290 * @return the entry hashcode
291 */
292 public int hashCode() {
293 return getName().hashCode();
294 }
295
296 /**
297 * Determine if the given entry is a descendant of this entry.
298 * Descendancy is determined by the name of the descendant
299 * starting with this entry's name.
300 *
301 * @param desc Entry to be checked as a descendent of this.
302 * @return True if entry is a descendant of this.
303 */
304 public boolean isDescendent(TarArchiveEntry desc) {
305 return desc.getName().startsWith(getName());
306 }
307
308 /**
309 * Get this entry's name.
310 *
311 * @return This entry's name.
312 */
313 public String getName() {
314 return name.toString();
315 }
316
317 /**
318 * Set this entry's name.
319 *
320 * @param name This entry's new name.
321 */
322 public void setName(String name) {
323 this.name = normalizeFileName(name);
324 }
325
326 /**
327 * Set the mode for this entry
328 *
329 * @param mode the mode for this entry
330 */
331 public void setMode(int mode) {
332 this.mode = mode;
333 }
334
335 /**
336 * Get this entry's link name.
337 *
338 * @return This entry's link name.
339 */
340 public String getLinkName() {
341 return linkName.toString();
342 }
343
344 /**
345 * Get this entry's user id.
346 *
347 * @return This entry's user id.
348 */
349 public int getUserId() {
350 return userId;
351 }
352
353 /**
354 * Set this entry's user id.
355 *
356 * @param userId This entry's new user id.
357 */
358 public void setUserId(int userId) {
359 this.userId = userId;
360 }
361
362 /**
363 * Get this entry's group id.
364 *
365 * @return This entry's group id.
366 */
367 public int getGroupId() {
368 return groupId;
369 }
370
371 /**
372 * Set this entry's group id.
373 *
374 * @param groupId This entry's new group id.
375 */
376 public void setGroupId(int groupId) {
377 this.groupId = groupId;
378 }
379
380 /**
381 * Get this entry's user name.
382 *
383 * @return This entry's user name.
384 */
385 public String getUserName() {
386 return userName.toString();
387 }
388
389 /**
390 * Set this entry's user name.
391 *
392 * @param userName This entry's new user name.
393 */
394 public void setUserName(String userName) {
395 this.userName = userName;
396 }
397
398 /**
399 * Get this entry's group name.
400 *
401 * @return This entry's group name.
402 */
403 public String getGroupName() {
404 return groupName.toString();
405 }
406
407 /**
408 * Set this entry's group name.
409 *
410 * @param groupName This entry's new group name.
411 */
412 public void setGroupName(String groupName) {
413 this.groupName = groupName;
414 }
415
416 /**
417 * Convenience method to set this entry's group and user ids.
418 *
419 * @param userId This entry's new user id.
420 * @param groupId This entry's new group id.
421 */
422 public void setIds(int userId, int groupId) {
423 setUserId(userId);
424 setGroupId(groupId);
425 }
426
427 /**
428 * Convenience method to set this entry's group and user names.
429 *
430 * @param userName This entry's new user name.
431 * @param groupName This entry's new group name.
432 */
433 public void setNames(String userName, String groupName) {
434 setUserName(userName);
435 setGroupName(groupName);
436 }
437
438 /**
439 * Set this entry's modification time. The parameter passed
440 * to this method is in "Java time".
441 *
442 * @param time This entry's new modification time.
443 */
444 public void setModTime(long time) {
445 modTime = time / MILLIS_PER_SECOND;
446 }
447
448 /**
449 * Set this entry's modification time.
450 *
451 * @param time This entry's new modification time.
452 */
453 public void setModTime(Date time) {
454 modTime = time.getTime() / MILLIS_PER_SECOND;
455 }
456
457 /**
458 * Set this entry's modification time.
459 *
460 * @return time This entry's new modification time.
461 */
462 public Date getModTime() {
463 return new Date(modTime * MILLIS_PER_SECOND);
464 }
465
466 /**
467 * Get this entry's file.
468 *
469 * @return This entry's file.
470 */
471 public File getFile() {
472 return file;
473 }
474
475 /**
476 * Get this entry's mode.
477 *
478 * @return This entry's mode.
479 */
480 public int getMode() {
481 return mode;
482 }
483
484 /**
485 * Get this entry's file size.
486 *
487 * @return This entry's file size.
488 */
489 public long getSize() {
490 return size;
491 }
492
493 /**
494 * Set this entry's file size.
495 *
496 * @param size This entry's new file size.
497 * @throws IllegalArgumentException if the size is < 0
498 * or > {@link TarConstants#MAXSIZE} (077777777777L).
499 */
500 public void setSize(long size) {
501 if (size > MAXSIZE || size < 0){
502 throw new IllegalArgumentException("Size is out of range: "+size);
503 }
504 this.size = size;
505 }
506
507
508 /**
509 * Indicate if this entry is a GNU long name block
510 *
511 * @return true if this is a long name extension provided by GNU tar
512 */
513 public boolean isGNULongNameEntry() {
514 return linkFlag == LF_GNUTYPE_LONGNAME
515 && name.toString().equals(GNU_LONGLINK);
516 }
517
518 /**
519 * Return whether or not this entry represents a directory.
520 *
521 * @return True if this entry is a directory.
522 */
523 public boolean isDirectory() {
524 if (file != null) {
525 return file.isDirectory();
526 }
527
528 if (linkFlag == LF_DIR) {
529 return true;
530 }
531
532 if (getName().endsWith("/")) {
533 return true;
534 }
535
536 return false;
537 }
538
539 /**
540 * If this entry represents a file, and the file is a directory, return
541 * an array of TarEntries for this entry's children.
542 *
543 * @return An array of TarEntry's for this entry's children.
544 */
545 public TarArchiveEntry[] getDirectoryEntries() {
546 if (file == null || !file.isDirectory()) {
547 return new TarArchiveEntry[0];
548 }
549
550 String[] list = file.list();
551 TarArchiveEntry[] result = new TarArchiveEntry[list.length];
552
553 for (int i = 0; i < list.length; ++i) {
554 result[i] = new TarArchiveEntry(new File(file, list[i]));
555 }
556
557 return result;
558 }
559
560 /**
561 * Write an entry's header information to a header buffer.
562 *
563 * @param outbuf The tar entry header buffer to fill in.
564 */
565 public void writeEntryHeader(byte[] outbuf) {
566 int offset = 0;
567
568 offset = TarUtils.formatNameBytes(name, outbuf, offset, NAMELEN);
569 offset = TarUtils.formatOctalBytes(mode, outbuf, offset, MODELEN);
570 offset = TarUtils.formatOctalBytes(userId, outbuf, offset, UIDLEN);
571 offset = TarUtils.formatOctalBytes(groupId, outbuf, offset, GIDLEN);
572 offset = TarUtils.formatLongOctalBytes(size, outbuf, offset, SIZELEN);
573 offset = TarUtils.formatLongOctalBytes(modTime, outbuf, offset, MODTIMELEN);
574
575 int csOffset = offset;
576
577 for (int c = 0; c < CHKSUMLEN; ++c) {
578 outbuf[offset++] = (byte) ' ';
579 }
580
581 outbuf[offset++] = linkFlag;
582 offset = TarUtils.formatNameBytes(linkName, outbuf, offset, NAMELEN);
583 offset = TarUtils.formatNameBytes(magic, outbuf, offset, MAGICLEN);
584 offset = TarUtils.formatNameBytes(version, outbuf, offset, VERSIONLEN);
585 offset = TarUtils.formatNameBytes(userName, outbuf, offset, UNAMELEN);
586 offset = TarUtils.formatNameBytes(groupName, outbuf, offset, GNAMELEN);
587 offset = TarUtils.formatOctalBytes(devMajor, outbuf, offset, DEVLEN);
588 offset = TarUtils.formatOctalBytes(devMinor, outbuf, offset, DEVLEN);
589
590 while (offset < outbuf.length) {
591 outbuf[offset++] = 0;
592 }
593
594 long chk = TarUtils.computeCheckSum(outbuf);
595
596 TarUtils.formatCheckSumOctalBytes(chk, outbuf, csOffset, CHKSUMLEN);
597 }
598
599 /**
600 * Parse an entry's header information from a header buffer.
601 *
602 * @param header The tar entry header buffer to get information from.
603 */
604 public void parseTarHeader(byte[] header) {
605 int offset = 0;
606
607 name = TarUtils.parseName(header, offset, NAMELEN);
608 offset += NAMELEN;
609 mode = (int) TarUtils.parseOctal(header, offset, MODELEN);
610 offset += MODELEN;
611 userId = (int) TarUtils.parseOctal(header, offset, UIDLEN);
612 offset += UIDLEN;
613 groupId = (int) TarUtils.parseOctal(header, offset, GIDLEN);
614 offset += GIDLEN;
615 size = TarUtils.parseOctal(header, offset, SIZELEN);
616 offset += SIZELEN;
617 modTime = TarUtils.parseOctal(header, offset, MODTIMELEN);
618 offset += MODTIMELEN;
619 offset += CHKSUMLEN;
620 linkFlag = header[offset++];
621 linkName = TarUtils.parseName(header, offset, NAMELEN);
622 offset += NAMELEN;
623 magic = TarUtils.parseName(header, offset, MAGICLEN);
624 offset += MAGICLEN;
625 version = TarUtils.parseName(header, offset, VERSIONLEN);
626 offset += VERSIONLEN;
627 userName = TarUtils.parseName(header, offset, UNAMELEN);
628 offset += UNAMELEN;
629 groupName = TarUtils.parseName(header, offset, GNAMELEN);
630 offset += GNAMELEN;
631 devMajor = (int) TarUtils.parseOctal(header, offset, DEVLEN);
632 offset += DEVLEN;
633 devMinor = (int) TarUtils.parseOctal(header, offset, DEVLEN);
634 }
635
636 /**
637 * Strips Windows' drive letter as well as any leading slashes,
638 * turns path separators into forward slahes.
639 */
640 private static String normalizeFileName(String fileName) {
641 String osname = System.getProperty("os.name").toLowerCase(Locale.US);
642
643 if (osname != null) {
644
645 // Strip off drive letters!
646 // REVIEW Would a better check be "(File.separator == '\')"?
647
648 if (osname.startsWith("windows")) {
649 if (fileName.length() > 2) {
650 char ch1 = fileName.charAt(0);
651 char ch2 = fileName.charAt(1);
652
653 if (ch2 == ':'
654 && ((ch1 >= 'a' && ch1 <= 'z')
655 || (ch1 >= 'A' && ch1 <= 'Z'))) {
656 fileName = fileName.substring(2);
657 }
658 }
659 } else if (osname.indexOf("netware") > -1) {
660 int colon = fileName.indexOf(':');
661 if (colon != -1) {
662 fileName = fileName.substring(colon + 1);
663 }
664 }
665 }
666
667 fileName = fileName.replace(File.separatorChar, '/');
668
669 // No absolute pathnames
670 // Windows (and Posix?) paths can start with "\\NetworkDrive\",
671 // so we loop on starting /'s.
672 while (fileName.startsWith("/")) {
673 fileName = fileName.substring(1);
674 }
675 return fileName;
676 }
677 }
678