CPIO(1L)                                               CPIO(1L)





NAME
       cpio - copy files to and from archives

SYNOPSIS
       cpio  {-o|--create}  [-0acvABLV]  [-C bytes] [-H format]
       [-M    message]    [-O    [[user@]host:]archive]     [-F
       [[user@]host:]archive]    [--file=[[user@]host:]archive]
       [--format=format] [--message=message] [--null] [--reset-
       access-time]  [--verbose]  [--dot]  [--append] [--block-
       size=blocks] [--dereference] [--io-size=bytes] [--quiet]
       [--force-local]  [--help] [--version] < name-list [> ar-
       chive]

       cpio {-i|--extract}  [-bcdfmnrtsuvBSV]  [-C  bytes]  [-E
       file]  [-H  format]  [-M message] [-R [user][:.][group]]
       [-I  [[user@]host:]archive]  [-F  [[user@]host:]archive]
       [--file=[[user@]host:]archive]      [--make-directories]
       [--nonmatching]           [--preserve-modification-time]
       [--numeric-uid-gid]  [--rename]  [--list] [--swap-bytes]
       [--swap] [--dot] [--unconditional] [--verbose] [--block-
       size=blocks]     [--swap-halfwords]    [--io-size=bytes]
       [--pattern-file=file]                  [--format=format]
       [--owner=[user][:.][group]]        [--no-preserve-owner]
       [--message=message]   [--force-local]   --absolute-file-
       names] [--sparse] [--only-verify-crc] [--quiet] [--help]
       [--version] [pattern...] [< archive]

       cpio      {-p|--pass-through}      [-0adlmuvLV]      [-R
       [user][:.][group]]     [--null]    [--reset-access-time]
       [--make-directories] [--link] [--quiet] [--preserve-mod-
       ification-time]  [--unconditional]  [--verbose]  [--dot]
       [--dereference]  [--owner=[user][:.][group]]  [--no-pre-
       serve-owner]  [--sparse]  [--help]  [--version] destina-
       tion-directory < name-list

DESCRIPTION
       This manual page documents  the  GNU  version  of  cpio.
       cpio  copies files into or out of a cpio or tar archive,
       which is a file that contains other files plus  informa-
       tion  about  them, such as their file name, owner, time-
       stamps, and access  permissions.   The  archive  can  be
       another  file  on  the disk, a magnetic tape, or a pipe.
       cpio has three operating modes.

       In copy-out mode, cpio copies files into an archive.  It
       reads a list of filenames, one per line, on the standard
       input, and writes the archive onto the standard  output.
       A  typical way to generate the list of filenames is with
       the find command; you should give find the -d option  to
       minimize  problems  with permissions on directories that
       are unwritable or not searchable.

       In copy-in mode, cpio copies files out of an archive  or
       lists  the  archive contents.  It reads the archive from
       the standard input.  Any non-option command  line  argu-
       ments are shell globbing patterns; only files in the ar-
       chive whose names match one or more  of  those  patterns
       are  copied  from  the archive.  Unlike in the shell, an
       initial `.' in a filename does match a wildcard  at  the
       start  of  a  pattern, and a `/' in a filename can match
       wildcards.  If no patterns  are  given,  all  files  are
       extracted.

       In  copy-pass mode, cpio copies files from one directory
       tree to another,  combining  the  copy-out  and  copy-in
       steps  without  actually using an archive.  It reads the
       list of files to  copy  from  the  standard  input;  the
       directory  into  which  it  will copy them is given as a
       non-option argument.

       cpio supports the following archive formats: binary, old
       ASCII,  new ASCII, crc, HPUX binary, HPUX old ASCII, old
       tar, and POSIX.1 tar.  The  binary  format  is  obsolete
       because  it encodes information about the files in a way
       that is not portable between different machine architec-
       tures.  The old ASCII format is portable between differ-
       ent machine architectures, but should  not  be  used  on
       file  systems  with  more  than  65536 i-nodes.  The new
       ASCII  format  is  portable  between  different  machine
       architectures  and  can be used on any size file system,
       but is not supported by all versions of cpio; currently,
       it  is  only supported by GNU and Unix System V R4.  The
       crc format is like the new ASCII format, but  also  con-
       tains  a  checksum  for  each file which cpio calculates
       when creating an archive and verifies when the  file  is
       extracted  from  the archive.  The HPUX formats are pro-
       vided for compatibility with HPUX's  cpio  which  stores
       device files differently.

       The  tar  format  is provided for compatibility with the
       tar program.  It can not be used to archive  files  with
       names longer than 100 characters, and can not be used to
       archive "special" (block or  character  devices)  files.
       The  POSIX.1 tar format can not be used to archive files
       with names longer than 255 characters (less unless  they
       have a "/" in just the right place).

       By  default,  cpio  creates  binary format archives, for
       compatibility with older cpio programs.  When extracting
       from  archives, cpio automatically recognizes which kind
       of archive it is reading and can read  archives  created
       on machines with a different byte-order.

       Some  of the options to cpio apply only to certain oper-
       ating modes; see the SYNOPSIS  section  for  a  list  of
       which options are allowed in which modes.

   OPTIONS
       -0, --null
              In  copy-out  and copy-pass modes, read a list of
              filenames terminated by a null character  instead
              of  a  newline, so that files whose names contain
              newlines can be archived.  GNU find is one way to
              produce a list of null-terminated filenames.

       -a, --reset-access-time
              Reset  the  access  times  of files after reading
              them, so that it does not  look  like  they  have
              just been read.

       -A, --append
              Append  to  an  existing  archive.  Only works in
              copy-out mode.  The archive must be a  disk  file
              specified with the -O or -F (--file) option.

       -b, --swap
              In copy-in mode, swap both halfwords of words and
              bytes of halfwords in the  data.   Equivalent  to
              -sS.   Use this option to convert 32-bit integers
              between big-endian and little-endian machines.

       -B     Set the I/O block size to 5120 bytes.   Initially
              the block size is 512 bytes.

       --block-size=BLOCK-SIZE
              Set the I/O block size to BLOCK-SIZE * 512 bytes.

       -c     Use the old portable (ASCII) archive format.

       -C IO-SIZE, --io-size=IO-SIZE
              Set the I/O block size to IO-SIZE bytes.

       -d, --make-directories
              Create leading directories where needed.

       -E FILE, --pattern-file=FILE
              In copy-in mode, read additional patterns  speci-
              fying  filenames  to  extract  or list from FILE.
              The lines of FILE are treated as if they had been
              non-option arguments to cpio.

       -f, --nonmatching
              Only  copy  files  that  do  not match any of the
              given patterns.

       -F, --file=archive
              Archive filename to use instead of standard input
              or  output.   To  use  a  tape  drive  on another
              machine as  the  archive,  use  a  filename  that
              starts  with  `HOSTNAME:'.   The  hostname can be
              preceded by a username and an `@' to  access  the
              remote  tape drive as that user, if you have per-
              mission to do so  (typically  an  entry  in  that
              user's `~/.rhosts' file).

       --force-local
              With -F, -I, or -O, take the archive file name to
              be a local file even  if  it  contains  a  colon,
              which  would  ordinarily  indicate  a remote host
              name.

       -H FORMAT, --format=FORMAT
              Use archive format FORMAT.  The valid formats are
              listed  below; the same names are also recognized
              in all-caps.  The default in copy-in mode  is  to
              automatically  detect  the archive format, and in
              copy-out mode is "bin".

              bin    The obsolete binary format.

              odc    The old (POSIX.1) portable format.

              newc   The new (SVR4) portable format, which sup-
                     ports  file systems having more than 65536
                     i-nodes.

              crc    The new  (SVR4)  portable  format  with  a
                     checksum added.

              tar    The old tar format.

              ustar  The  POSIX.1  tar format.  Also recognizes
                     GNU tar archives, which  are  similar  but
                     not identical.

              hpbin  The  obsolete binary format used by HPUX's
                     cpio (which stores  device  files  differ-
                     ently).

              hpodc  The  portable  format  used by HPUX's cpio
                     (which stores device files differently).

       -i, --extract
              Run in copy-in mode.

       -I archive
              Archive  filename  to  use  instead  of  standard
              input.  To use a tape drive on another machine as
              the archive, use  a  filename  that  starts  with
              `HOSTNAME:'.   The  hostname can be preceded by a
              username and an `@' to  access  the  remote  tape
              drive  as that user, if you have permission to do
              so (typically an entry in that user's `~/.rhosts'
              file).

       -k     Ignored; for compatibility with other versions of
              cpio.

       -l, --link
              Link files instead of copying them, when possible
              (usable only with the -p option).

       -L, --dereference
              Dereference  symbolic  links (copy the files that
              they point to instead of copying the links).

       -m, --preserve-modification-time
              Retain previous file modification times when cre-
              ating files.

       -M MESSAGE, --message=MESSAGE
              Print  MESSAGE  when  the  end of a volume of the
              backup media (such as a tape or a floppy disk) is
              reached,  to prompt the user to insert a new vol-
              ume.  If MESSAGE contains the string "%d", it  is
              replaced  by  the current volume number (starting
              at 1).

       -n, --numeric-uid-gid
              In the verbose table of  contents  listing,  show
              numeric  UID  and GID instead of translating them
              into names.

        --no-absolute-filenames
              In copy-in mode, create all files relative to the
              current  directory, even if they have an absolute
              file name in the archive.

        --no-preserve-owner
              In copy-in mode and copy-pass mode, do not change
              the  ownership  of the files; leave them owned by
              the user extracting them.  This  is  the  default
              for  non-root  users,  so  that users on System V
              don't inadvertently give away files.

       -o, --create
              Run in copy-out mode.

       -O archive
              Archive filename to use instead of standard  out-
              put.   To  use a tape drive on another machine as
              the archive, use  a  filename  that  starts  with
              `HOSTNAME:'.   The  hostname can be preceded by a
              username and an `@' to  access  the  remote  tape
              drive  as that user, if you have permission to do
              so (typically an entry in that user's `~/.rhosts'
              file).

        --only-verify-crc
              When  reading  a  CRC  format  archive in copy-in
              mode, only verify the CRC's of each file  in  the
              archive, don't actually extract the files.

       -p, --pass-through
              Run in copy-pass mode.

       --quiet
              Do not print the number of blocks copied.

       -r, --rename
              Interactively rename files.

       -R [user][:.][group], --owner [user][:.][group]
              In  copy-out  and copy-pass modes, set the owner-
              ship of all files created to the  specified  user
              and/or  group.   Either the user or the group, or
              both, must be present.  If the group  is  omitted
              but  the  ":" or "."  separator is given, use the
              given user's login group.   Only  the  super-user
              can change files' ownership.

       --sparse
              In copy-out and copy-pass modes, write files with
              large blocks of zeros as sparse files.

       -s, --swap-bytes
              In copy-in mode, swap the bytes of each  halfword
              (pair of bytes) in the files.

       -S, --swap-halfwords
              In  copy-in mode, swap the halfwords of each word
              (4 bytes) in the files.

       -t, --list
              Print a table of contents of the input.

       -u, --unconditional
              Replace all  files,  without  asking  whether  to
              replace existing newer files with older files.

       -v, --verbose
              List the files processed, or with -t, give an `ls
              -l' style table of contents listing.  In  a  ver-
              bose  table  of contents of a ustar archive, user
              and group names in the archive that do not  exist
              on  the  local  system  are replaced by the names
              that correspond locally to the  numeric  UID  and
              GID stored in the archive.

       -V --dot
              Print a "." for each file processed.

       --version
              Print the cpio program version number and exit.



                                                       CPIO(1L)
