org.apache.commons.compress.archivers.cpio

## Class CpioArchiveEntry

- java.lang.Object
- - org.apache.commons.compress.archivers.cpio.CpioArchiveEntry

- All Implemented Interfaces:
    ArchiveEntry, CpioConstants

      public class CpioArchiveEntry
      extends Object
      implements CpioConstants, ArchiveEntry

  A cpio archive consists of a sequence of files. There are several types of headers defined in two categories of new and old format. The headers are recognized by magic numbers:
  - "070701" ASCII for new portable format
  - "070702" ASCII for new portable format with CRC
  - "070707" ASCII for old ascii (also known as Portable ASCII, odc or old character format
  - 070707 binary for old binary

  The old binary format is limited to 16 bits for user id, group id, device, and inode numbers. It is limited to 4 gigabyte file sizes. The old ASCII format is limited to 18 bits for the user id, group id, device, and inode numbers. It is limited to 8 gigabyte file sizes. The new ASCII format is limited to 4 gigabyte file sizes. CPIO 2.5 knows also about tar, but it is not recognized here.

  ## OLD FORMAT

  Each file has a 76 (ascii) / 26 (binary) byte header, a variable length, NUL terminated file name, and variable length file data. A header for a file name "TRAILER!!!" indicates the end of the archive.

  All the fields in the header are ISO 646 (approximately ASCII) strings of octal numbers, left padded, not NUL terminated.

       FIELDNAME        NOTES
       c_magic          The integer value octal 070707.  This value can be used to deter-
                        mine whether this archive is written with little-endian or big-
                        endian integers.
       c_dev            Device that contains a directory entry for this file
       c_ino            I-node number that identifies the input file to the file system
       c_mode           The mode specifies both the regular permissions and the file type.
       c_uid            Numeric User ID of the owner of the input file
       c_gid            Numeric Group ID of the owner of the input file
       c_nlink          Number of links that are connected to the input file
       c_rdev           For block special and character special entries, this field
                        contains the associated device number.  For all other entry types,
                        it should be set to zero by writers and ignored by readers.
       c_mtime[2]       Modification time of the file, indicated as the number of seconds
                        since the start of the epoch, 00:00:00 UTC January 1, 1970.  The
                        four-byte integer is stored with the most-significant 16 bits
                        first followed by the least-significant 16 bits.  Each of the two
                        16 bit values are stored in machine-native byte order.
       c_namesize       Length of the path name, including the terminating null byte
       c_filesize[2]    Length of the file in bytes. This is the length of the data
                        section that follows the header structure. Must be 0 for
                        FIFOs and directories

       All fields are unsigned short fields with 16-bit integer values
       apart from c_mtime and c_filesize which are 32-bit integer values

  If necessary, the file name and file data are padded with a NUL byte to an even length

  Special files, directories, and the trailer are recorded with the h_filesize field equal to 0.

  In the ASCII version of this format, the 16-bit entries are represented as 6-byte octal numbers, and the 32-bit entries are represented as 11-byte octal numbers. No padding is added.

  ### NEW FORMAT

  Each file has a 110 byte header, a variable length, NUL terminated file name, and variable length file data. A header for a file name "TRAILER!!!" indicates the end of the archive. All the fields in the header are ISO 646 (approximately ASCII) strings of hexadecimal numbers, left padded, not NUL terminated.

       FIELDNAME        NOTES
       c_magic[6]       The string 070701 for new ASCII, the string 070702 for new ASCII with CRC
       c_ino[8]
       c_mode[8]
       c_uid[8]
       c_gid[8]
       c_nlink[8]
       c_mtim[8]
       c_filesize[8]    must be 0 for FIFOs and directories
       c_maj[8]
       c_min[8]
       c_rmaj[8]        only valid for chr and blk special files
       c_rmin[8]        only valid for chr and blk special files
       c_namesize[8]    count includes terminating NUL in pathname
       c_check[8]       0 for "new" portable format; for CRC format
                        the sum of all the bytes in the file

  New ASCII Format The "new" ASCII format uses 8-byte hexadecimal fields for all numbers and separates device numbers into separate fields for major and minor numbers.

  The pathname is followed by NUL bytes so that the total size of the fixed header plus pathname is a multiple of four. Likewise, the file data is padded to a multiple of four bytes.

  This class uses mutable fields and is not considered to be threadsafe.

  Based on code from the jRPM project (http://jrpm.sourceforge.net).

  The MAGIC numbers and other constants are defined in `CpioConstants`

  N.B. does not handle the cpio "tar" format

  See Also:
    https://people.freebsd.org/~kientzle/libarchive/man/cpio.5.txt
  This class is not thread-safe

- - ### Field Summary

    - ### Fields inherited from interface org.apache.commons.compress.archivers.cpio.CpioConstants

      `BLOCK_SIZE, C_IRGRP, C_IROTH, C_IRUSR, C_ISBLK, C_ISCHR, C_ISDIR, C_ISFIFO, C_ISGID, C_ISLNK, C_ISNWK, C_ISREG, C_ISSOCK, C_ISUID, C_ISVTX, C_IWGRP, C_IWOTH, C_IWUSR, C_IXGRP, C_IXOTH, C_IXUSR, CPIO_TRAILER, FORMAT_NEW, FORMAT_NEW_CRC, FORMAT_NEW_MASK, FORMAT_OLD_ASCII, FORMAT_OLD_BINARY, FORMAT_OLD_MASK, MAGIC_NEW, MAGIC_NEW_CRC, MAGIC_OLD_ASCII, MAGIC_OLD_BINARY, S_IFMT`

    - ### Fields inherited from interface org.apache.commons.compress.archivers.ArchiveEntry

      `SIZE_UNKNOWN`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CpioArchiveEntry(File inputFile, String entryName)` Creates a CpioArchiveEntry with a specified name for a specified file.
    `CpioArchiveEntry(Path inputPath, String entryName, LinkOption... options)` Creates a CpioArchiveEntry with a specified name for a specified file.
    `CpioArchiveEntry(short format)` Creates a CpioArchiveEntry with a specified format.
    `CpioArchiveEntry(short format, File inputFile, String entryName)` Creates a CpioArchiveEntry with a specified name for a specified file.
    `CpioArchiveEntry(short format, Path inputPath, String entryName, LinkOption... options)` Creates a CpioArchiveEntry with a specified name for a specified path.
    `CpioArchiveEntry(short format, String name)` Creates a CpioArchiveEntry with a specified name.
    `CpioArchiveEntry(short format, String name, long size)` Creates a CpioArchiveEntry with a specified name.
    `CpioArchiveEntry(String name)` Creates a CpioArchiveEntry with a specified name.
    `CpioArchiveEntry(String name, long size)` Creates a CpioArchiveEntry with a specified name.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object obj)`
    `int` | `getAlignmentBoundary()` Gets the alignment boundary for this CPIO format
    `long` | `getChksum()` Gets the checksum.
    `int` | `getDataPadCount()` Gets the number of bytes needed to pad the data to the alignment boundary.
    `long` | `getDevice()` Gets the device id.
    `long` | `getDeviceMaj()` Gets the major device id.
    `long` | `getDeviceMin()` Gets the minor device id
    `short` | `getFormat()` Gets the format for this entry.
    `long` | `getGID()` Gets the group id.
    `int` | `getHeaderPadCount()` Deprecated. This method doesn't properly work for multi-byte encodings. And creates corrupt archives. Use `getHeaderPadCount(Charset)` or `getHeaderPadCount(long)` in any case.
    `int` | `getHeaderPadCount(Charset charset)` Gets the number of bytes needed to pad the header to the alignment boundary.
    `int` | `getHeaderPadCount(long nameSize)` Gets the number of bytes needed to pad the header to the alignment boundary.
    `int` | `getHeaderSize()` Gets the header size for this CPIO format
    `long` | `getInode()` Sets the inode.
    `Date` | `getLastModifiedDate()` Gets the last modified date of this entry.
    `long` | `getMode()` Gets the mode of this entry (e.g.
    `String` | `getName()` Gets the name.
    `long` | `getNumberOfLinks()` Gets the number of links.
    `long` | `getRemoteDevice()` Gets the remote device id.
    `long` | `getRemoteDeviceMaj()` Gets the remote major device id.
    `long` | `getRemoteDeviceMin()` Gets the remote minor device id.
    `long` | `getSize()` Gets the filesize.
    `long` | `getTime()` Gets the time in seconds.
    `long` | `getUID()` Gets the user id.
    `int` | `hashCode()`
    `boolean` | `isBlockDevice()` Checks if this entry represents a block device.
    `boolean` | `isCharacterDevice()` Checks if this entry represents a character device.
    `boolean` | `isDirectory()` Checks if this entry represents a directory.
    `boolean` | `isNetwork()` Checks if this entry represents a network device.
    `boolean` | `isPipe()` Checks if this entry represents a pipe.
    `boolean` | `isRegularFile()` Checks if this entry represents a regular file.
    `boolean` | `isSocket()` Checks if this entry represents a socket.
    `boolean` | `isSymbolicLink()` Checks if this entry represents a symbolic link.
    `void` | `setChksum(long chksum)` Sets the checksum.
    `void` | `setDevice(long device)` Sets the device id.
    `void` | `setDeviceMaj(long maj)` Sets major device id.
    `void` | `setDeviceMin(long min)` Sets the minor device id
    `void` | `setGID(long gid)` Sets the group id.
    `void` | `setInode(long inode)` Sets the inode.
    `void` | `setMode(long mode)` Sets the mode of this entry (e.g.
    `void` | `setName(String name)` Sets the name.
    `void` | `setNumberOfLinks(long nlink)` Sets the number of links.
    `void` | `setRemoteDevice(long device)` Sets the remote device id.
    `void` | `setRemoteDeviceMaj(long rmaj)` Sets the remote major device id.
    `void` | `setRemoteDeviceMin(long rmin)` Sets the remote minor device id.
    `void` | `setSize(long size)` Sets the filesize.
    `void` | `setTime(FileTime time)` Sets the time.
    `void` | `setTime(long time)` Sets the time in seconds.
    `void` | `setUID(long uid)` Sets the user id.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CpioArchiveEntry

          public CpioArchiveEntry(File inputFile,
                                  String entryName)

      Creates a CpioArchiveEntry with a specified name for a specified file. The format of this entry will be the new format.
      Parameters:
        `inputFile` - The file to gather information from.
        `entryName` - The name of this entry.

    - #### CpioArchiveEntry

          public CpioArchiveEntry(Path inputPath,
                                  String entryName,
                                  LinkOption... options)
                           throws IOException

      Creates a CpioArchiveEntry with a specified name for a specified file. The format of this entry will be the new format.
      Parameters:
        `inputPath` - The file to gather information from.
        `entryName` - The name of this entry.
        `options` - options indicating how symbolic links are handled.
      Throws:
        `IOException` - if an I/O error occurs
      Since:
        1.21

    - #### CpioArchiveEntry

          public CpioArchiveEntry(short format)

      Creates a CpioArchiveEntry with a specified format.
      Parameters:
        `format` - The cpio format for this entry.

        Possible format values are:

             CpioConstants.FORMAT_NEW
             CpioConstants.FORMAT_NEW_CRC
             CpioConstants.FORMAT_OLD_BINARY
             CpioConstants.FORMAT_OLD_ASCII

    - #### CpioArchiveEntry

          public CpioArchiveEntry(short format,
                                  File inputFile,
                                  String entryName)

      Creates a CpioArchiveEntry with a specified name for a specified file.
      Parameters:
        `format` - The cpio format for this entry.
        `inputFile` - The file to gather information from.
        `entryName` - The name of this entry.

        Possible format values are:

             CpioConstants.FORMAT_NEW
             CpioConstants.FORMAT_NEW_CRC
             CpioConstants.FORMAT_OLD_BINARY
             CpioConstants.FORMAT_OLD_ASCII

      Since:
        1.1

    - #### CpioArchiveEntry

          public CpioArchiveEntry(short format,
                                  Path inputPath,
                                  String entryName,
                                  LinkOption... options)
                           throws IOException

      Creates a CpioArchiveEntry with a specified name for a specified path.
      Parameters:
        `format` - The cpio format for this entry.
        `inputPath` - The file to gather information from.
        `entryName` - The name of this entry.

        Possible format values are:

             CpioConstants.FORMAT_NEW
             CpioConstants.FORMAT_NEW_CRC
             CpioConstants.FORMAT_OLD_BINARY
             CpioConstants.FORMAT_OLD_ASCII

        `options` - options indicating how symbolic links are handled.
      Throws:
        `IOException` - if an I/O error occurs
      Since:
        1.21

    - #### CpioArchiveEntry

          public CpioArchiveEntry(short format,
                                  String name)

      Creates a CpioArchiveEntry with a specified name.
      Parameters:
        `format` - The cpio format for this entry.
        `name` - The name of this entry.

        Possible format values are:

             CpioConstants.FORMAT_NEW
             CpioConstants.FORMAT_NEW_CRC
             CpioConstants.FORMAT_OLD_BINARY
             CpioConstants.FORMAT_OLD_ASCII

      Since:
        1.1

    - #### CpioArchiveEntry

          public CpioArchiveEntry(short format,
                                  String name,
                                  long size)

      Creates a CpioArchiveEntry with a specified name.
      Parameters:
        `format` - The cpio format for this entry.
        `name` - The name of this entry.
        `size` - The size of this entry

        Possible format values are:

             CpioConstants.FORMAT_NEW
             CpioConstants.FORMAT_NEW_CRC
             CpioConstants.FORMAT_OLD_BINARY
             CpioConstants.FORMAT_OLD_ASCII

      Since:
        1.1

    - #### CpioArchiveEntry

          public CpioArchiveEntry(String name)

      Creates a CpioArchiveEntry with a specified name. The format of this entry will be the new format.
      Parameters:
        `name` - The name of this entry.

    - #### CpioArchiveEntry

          public CpioArchiveEntry(String name,
                                  long size)

      Creates a CpioArchiveEntry with a specified name. The format of this entry will be the new format.
      Parameters:
        `name` - The name of this entry.
        `size` - The size of this entry

  - ### Method Detail

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### getAlignmentBoundary

          public int getAlignmentBoundary()

      Gets the alignment boundary for this CPIO format
      Returns:
        Returns the aligment boundary (0, 2, 4) in bytes

    - #### getChksum

          public long getChksum()

      Gets the checksum. Only supported for the new formats.
      Returns:
        Returns the checksum.
      Throws:
        `UnsupportedOperationException` - if the format is not a new format

    - #### getDataPadCount

          public int getDataPadCount()

      Gets the number of bytes needed to pad the data to the alignment boundary.
      Returns:
        the number of bytes needed to pad the data (0,1,2,3)

    - #### getDevice

          public long getDevice()

      Gets the device id.
      Returns:
        Returns the device id.
      Throws:
        `UnsupportedOperationException` - if this method is called for a CpioArchiveEntry with a new format.

    - #### getDeviceMaj

          public long getDeviceMaj()

      Gets the major device id.
      Returns:
        Returns the major device id.
      Throws:
        `UnsupportedOperationException` - if this method is called for a CpioArchiveEntry with an old format.

    - #### getDeviceMin

          public long getDeviceMin()

      Gets the minor device id
      Returns:
        Returns the minor device id.
      Throws:
        `UnsupportedOperationException` - if format is not a new format

    - #### getFormat

          public short getFormat()

      Gets the format for this entry.
      Returns:
        Returns the format.

    - #### getGID

          public long getGID()

      Gets the group id.
      Returns:
        Returns the group id.

    - #### getHeaderPadCount

          @Deprecated
          public int getHeaderPadCount()

      Deprecated. This method doesn't properly work for multi-byte encodings. And creates corrupt archives. Use `getHeaderPadCount(Charset)` or `getHeaderPadCount(long)` in any case.
      Gets the number of bytes needed to pad the header to the alignment boundary.
      Returns:
        the number of bytes needed to pad the header (0,1,2,3)

    - #### getHeaderPadCount

          public int getHeaderPadCount(Charset charset)

      Gets the number of bytes needed to pad the header to the alignment boundary.
      Parameters:
        `charset` - The character set used to encode the entry name in the stream.
      Returns:
        the number of bytes needed to pad the header (0,1,2,3)
      Since:
        1.18

    - #### getHeaderPadCount

          public int getHeaderPadCount(long nameSize)

      Gets the number of bytes needed to pad the header to the alignment boundary.
      Parameters:
        `nameSize` - The length of the name in bytes, as read in the stream. Without the trailing zero byte.
      Returns:
        the number of bytes needed to pad the header (0,1,2,3)
      Since:
        1.18

    - #### getHeaderSize

          public int getHeaderSize()

      Gets the header size for this CPIO format
      Returns:
        Returns the header size in bytes.

    - #### getInode

          public long getInode()

      Sets the inode.
      Returns:
        Returns the inode.

    - #### getLastModifiedDate

          public Date getLastModifiedDate()

      Description copied from interface: `ArchiveEntry`
      Gets the last modified date of this entry.
      Specified by:
        `getLastModifiedDate` in interface `ArchiveEntry`
      Returns:
        the last modified date of this entry.

    - #### getMode

          public long getMode()

      Gets the mode of this entry (e.g. directory, regular file).
      Returns:
        Returns the mode.

    - #### getName

          public String getName()

      Gets the name.

      This method returns the raw name as it is stored inside of the archive.

      Specified by:
        `getName` in interface `ArchiveEntry`
      Returns:
        Returns the name.

    - #### getNumberOfLinks

          public long getNumberOfLinks()

      Gets the number of links.
      Returns:
        Returns the number of links.

    - #### getRemoteDevice

          public long getRemoteDevice()

      Gets the remote device id.
      Returns:
        Returns the remote device id.
      Throws:
        `UnsupportedOperationException` - if this method is called for a CpioArchiveEntry with a new format.

    - #### getRemoteDeviceMaj

          public long getRemoteDeviceMaj()

      Gets the remote major device id.
      Returns:
        Returns the remote major device id.
      Throws:
        `UnsupportedOperationException` - if this method is called for a CpioArchiveEntry with an old format.

    - #### getRemoteDeviceMin

          public long getRemoteDeviceMin()

      Gets the remote minor device id.
      Returns:
        Returns the remote minor device id.
      Throws:
        `UnsupportedOperationException` - if this method is called for a CpioArchiveEntry with an old format.

    - #### getSize

          public long getSize()

      Gets the filesize.
      Specified by:
        `getSize` in interface `ArchiveEntry`
      Returns:
        Returns the filesize.
      See Also:
        `ArchiveEntry.getSize()`

    - #### getTime

          public long getTime()

      Gets the time in seconds.
      Returns:
        Returns the time.

    - #### getUID

          public long getUID()

      Gets the user id.
      Returns:
        Returns the user id.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### isBlockDevice

          public boolean isBlockDevice()

      Checks if this entry represents a block device.
      Returns:
        TRUE if this entry is a block device.

    - #### isCharacterDevice

          public boolean isCharacterDevice()

      Checks if this entry represents a character device.
      Returns:
        TRUE if this entry is a character device.

    - #### isDirectory

          public boolean isDirectory()

      Checks if this entry represents a directory.
      Specified by:
        `isDirectory` in interface `ArchiveEntry`
      Returns:
        TRUE if this entry is a directory.

    - #### isNetwork

          public boolean isNetwork()

      Checks if this entry represents a network device.
      Returns:
        TRUE if this entry is a network device.

    - #### isPipe

          public boolean isPipe()

      Checks if this entry represents a pipe.
      Returns:
        TRUE if this entry is a pipe.

    - #### isRegularFile

          public boolean isRegularFile()

      Checks if this entry represents a regular file.
      Returns:
        TRUE if this entry is a regular file.

    - #### isSocket

          public boolean isSocket()

      Checks if this entry represents a socket.
      Returns:
        TRUE if this entry is a socket.

    - #### isSymbolicLink

          public boolean isSymbolicLink()

      Checks if this entry represents a symbolic link.
      Returns:
        TRUE if this entry is a symbolic link.

    - #### setChksum

          public void setChksum(long chksum)

      Sets the checksum. The checksum is calculated by adding all bytes of a file to transfer (crc += buf[pos] & 0xFF).
      Parameters:
        `chksum` - The checksum to set.

    - #### setDevice

          public void setDevice(long device)

      Sets the device id.
      Parameters:
        `device` - The device id to set.
      Throws:
        `UnsupportedOperationException` - if this method is called for a CpioArchiveEntry with a new format.

    - #### setDeviceMaj

          public void setDeviceMaj(long maj)

      Sets major device id.
      Parameters:
        `maj` - The major device id to set.

    - #### setDeviceMin

          public void setDeviceMin(long min)

      Sets the minor device id
      Parameters:
        `min` - The minor device id to set.

    - #### setGID

          public void setGID(long gid)

      Sets the group id.
      Parameters:
        `gid` - The group id to set.

    - #### setInode

          public void setInode(long inode)

      Sets the inode.
      Parameters:
        `inode` - The inode to set.

    - #### setMode

          public void setMode(long mode)

      Sets the mode of this entry (e.g. directory, regular file).
      Parameters:
        `mode` - The mode to set.

    - #### setName

          public void setName(String name)

      Sets the name.
      Parameters:
        `name` - The name to set.

    - #### setNumberOfLinks

          public void setNumberOfLinks(long nlink)

      Sets the number of links.
      Parameters:
        `nlink` - The number of links to set.

    - #### setRemoteDevice

          public void setRemoteDevice(long device)

      Sets the remote device id.
      Parameters:
        `device` - The remote device id to set.
      Throws:
        `UnsupportedOperationException` - if this method is called for a CpioArchiveEntry with a new format.

    - #### setRemoteDeviceMaj

          public void setRemoteDeviceMaj(long rmaj)

      Sets the remote major device id.
      Parameters:
        `rmaj` - The remote major device id to set.
      Throws:
        `UnsupportedOperationException` - if this method is called for a CpioArchiveEntry with an old format.

    - #### setRemoteDeviceMin

          public void setRemoteDeviceMin(long rmin)

      Sets the remote minor device id.
      Parameters:
        `rmin` - The remote minor device id to set.
      Throws:
        `UnsupportedOperationException` - if this method is called for a CpioArchiveEntry with an old format.

    - #### setSize

          public void setSize(long size)

      Sets the filesize.
      Parameters:
        `size` - The filesize to set.

    - #### setTime

          public void setTime(FileTime time)

      Sets the time.
      Parameters:
        `time` - The time to set.

    - #### setTime

          public void setTime(long time)

      Sets the time in seconds.
      Parameters:
        `time` - The time to set.

    - #### setUID

          public void setUID(long uid)

      Sets the user id.
      Parameters:
        `uid` - The user id to set.

Copyright © 2002–2022 The Apache Software Foundation. All rights reserved.