Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1‎ > ‎


     cpio - copy file archives in and out

     cpio -i [-bBcdfkmPrsStuvV6,t;] [-C bufsize] [-E file]
         [-H header] [-I  [-M message]] [-R id] [pattern]...

     cpio -o [-aABcLPvV,t;] [-C bufsize] [-H header]
         [-O file [-M message]]

     cpio -p [-adlLmPuvV,t;] [-R id] directory

     The cpio command  copies  files  into  and  out  of  a  cpio
     archive. The cpio archive may span multiple volumes. The -i,
     -o, and -p options select the action to  be  performed.  The
     following  list describes each of the actions. These actions
     are mutually exclusive.

  Copy In Mode
     cpio -i (copy in) extracts files from  the  standard  input,
     which  is  assumed  to  be the product of a previous cpio -o
     command. Only files with names that match one  of  the  pat-
     terns are selected. See sh(1) and OPERANDS for more informa-
     tion about pattern. Extracted files are conditionally copied
     into  the  current  directory  tree,  based  on  the options
     described below. The permissions of the files will be  those
     of the previous cpio -o command. The owner and group will be
     the same as the current user, unless the current user is the
     super-user. If this is the case, owner and group will be the
     same as those resulting from the previous cpio  -o  command.
     Notice  that  if cpio -i tries to create a file that already
     exists and the existing file is  the  same  age  or  younger
     (newer),  cpio will output a warning message and not replace
     the file. The -u  option  can  be  used  to  unconditionally
     overwrite the existing file.

  Copy Out Mode
     cpio -o (copy out) reads a list of file path names from  the
     standard  input  and copies those files to the standard out-
     put, together with path name and status information  in  the
     form  of  a  cpio  archive. Output is padded to an 8192-byte
     boundary by default or  to  the  user-specified  block  size
     (with  the  -B  or  -C  options) or to some device-dependent
     block size where necessary (as with the CTC tape).

  Pass Mode
     cpio -p (pass) reads a list of  file  path  names  from  the
     standard input and conditionally copies those files into the
     destination directory tree, based on the  options  described

     Note: cpio assumes four-byte words.

     If, when writing to a character device (-o) or reading  from
     a  character  device  (-i), cpio reaches the end of a medium
     (such as the end of a diskette), and the -O and  -I  options
     are not used, cpio prints the following message:

       To continue, type device/file name when ready.

     To continue, you must replace the medium and type the  char-
     acter  special  device name (/dev/rdiskette for example) and
     press RETURN. You may want to continue by directing cpio  to
     use  a different device. For example, if you have two floppy
     drives you may want to  switch  between  them  so  cpio  can
     proceed while you are changing the floppies. Press RETURN to
     cause the cpio process to exit.

     The following options are supported:

     -i    (copy in) Reads an archive from the standard input and
           conditionally  extracts  the files contained in it and
           places them into the current directory tree.

     -o    (copy out) Reads a list of file path  names  from  the
           standard  input and copies those files to the standard
           output in the form of a cpio archive.

     -p    (pass) Reads a list of file path names from the  stan-
           dard  input  and conditionally copies those files into
           the destination directory tree.

     The following options can be appended in any sequence to the
     -i, -o, or -p options:

     -a            Resets access times of input files after  they
                   have been copied, making cpio's access invisi-
                   ble. Access times are  not  reset  for  linked
                   files when cpio -pla is specified.

     -A            Appends files to an  archive.  The  -A  option
                   requires   the  -O  option.  Valid  only  with
                   archives that are files, or that are on floppy
                   diskettes  or hard disk partitions. The effect
                   on files that are linked in the existing  por-
                   tion of the archive is unpredictable.

     -b            Reverses the order of the  bytes  within  each
                   word. Use only with the -i option.

     -B            Blocks input/output 5120 bytes to the  record.
                   The  default  buffer  size  is 8192 bytes when
                   this and the -C options are not used. -B  does
                   not apply to the -p (pass) option.

     -c            Reads or writes header  information  in  ASCII
                   character  form  for portability. There are no
                   UID or GID restrictions associated  with  this
                   header  format.  Use this option between SVR4-
                   based machines, or the -H odc  option  between
                   unknown  machines.  The  -c option implies the
                   use of expanded device numbers, which are only
                   supported    on   SVR4-based   systems.   When
                   transferring files between SunOS 4 or Interac-
                   tive   UNIX  and  the  Solaris  2.6  Operating
                   environment or  compatible  versions,  use  -H

     -C bufsize    Blocks  input/output  bufsize  bytes  to   the
                   record,  where  bufsize is replaced by a posi-
                   tive integer. The default buffer size is  8192
                   bytes  when  this and -B options are not used.
                   -C does not apply to the -p (pass) option.

     -d            Creates directories as needed.

     -E file       Specifies an input file (file) that contains a
                   list  of  filenames  to  be extracted from the
                   archive (one filename per line).

     -f            Copies in all files except those in  patterns.
                   See OPERANDS for a description of pattern.

     -H header     Reads or writes header information  in  header
                   format.  Always  use  this  option  or  the -c
                   option when the  origin  and  the  destination
                   machines  are  different types. This option is
                   mutually exclusive with options -c and -6.

                   Valid values for header are:

                   bar              bar  head  and  format.  Used
                                    only  with  the  -i  option (
                                    read only).

                   crc | CRC        ASCII  header  with  expanded
                                    device  numbers  and an addi-
                                    tional   per-file   checksum.
                                    There  are no UID or GID res-
                                    trictions   associated   with
                                    this header format.

                   odc              ASCII header with small  dev-
                                    ice   numbers.  This  is  the
                                    IEEE/P1003  Data  Interchange
                                    Standard cpio header and for-
                                    mat. It has the widest  range
                                    of  portability of any of the
                                    header  formats.  It  is  the
                                    official format for transfer-
                                    ring  files  between   POSIX-
                                    conforming systems (see stan-
                                    dards(5)). Use this format to
                                    communicate  with SunOS 4 and
                                    Interactive UNIX. This header
                                    format  allows  UIDs and GIDs
                                    up to 262143 to be stored  in
                                    the header.

                   tar | TAR        tar header and  format.  This
                                    is an older tar header format
                                    that allows UIDs and GIDs  up
                                    to  2097151  to  be stored in
                                    the header.  It  is  provided
                                    for  the  reading  of  legacy
                                    archives only,  that  is,  in
                                    conjunction with option -i.

                                    Specifying this archive  for-
                                    mat  with  option  -o has the
                                    same effect as specifying the
                                    "ustar"  format:  the  output
                                    archive is in  ustar  format,
                                    and  must  be  read  using -H

                   ustar | USTAR    IEEE/P1003  Data  Interchange
                                    Standard  tar header and for-
                                    mat.   This   header   format
                                    allows  UIDs  and  GIDs up to
                                    2097151 to be stored  in  the

                   Files with UIDs  and  GIDs  greater  than  the
                   limit  stated  above will be archived with the
                   UID and GID of 60001. To transfer a large file
                   (8  Gb  -  1  byte),  the header format can be
                   tar|TAR, ustar|USTAR, or odc only.

     -I file       Reads  the  contents  of  file  as  an   input
                   archive,  instead  of  the  standard input. If
                   file is a character special  device,  and  the
                   current   medium  has  been  completely  read,
                   replace the medium and press  RETURN  to  con-
                   tinue  to the next medium. This option is used
                   only with the -i option.

     -k            Attempts to skip corrupted  file  headers  and
                   I/O  errors  that  may  be encountered. If you
                   want to copy files from a medium that is  cor-
                   rupted  or  out  of sequence, this option lets
                   you read only those files with  good  headers.
                   For  cpio  archives  that  contain  other cpio
                   archives, if an error is encountered, cpio may
                   terminate prematurely. cpio will find the next
                   good header, which may be one  for  a  smaller
                   archive,   and   terminate  when  the  smaller
                   archive's trailer is  encountered.   Use  only
                   with the -i option.

     -l            In pass mode, makes  hard  links  between  the
                   source  and  destination whenever possible. If
                   the -L option is also specified, the hard link
                   will  be  to  the file referred to by the sym-
                   bolic link. Otherwise, the hard link  will  be
                   to the symbolic link itself. Use only with the
                   -p option.

     -L            Follows symbolic links. If a symbolic link  to
                   a   directory  is  encountered,  archives  the
                   directory referred to by the link,  using  the
                   name of the link. Otherwise, archives the file
                   referred to by the link, using the name of the

     -m            Retains previous file modification time.  This
                   option  is ineffective on directories that are
                   being copied.

     -M message    Defines a message to use when switching media.
                   When  you use the -O or -I options and specify
                   a character special device, you can  use  this
                   option  to  define the message that is printed
                   when you reach the end of the medium.  One  %d
                   can be placed in message to print the sequence
                   number of the next medium needed to continue.

     -O file       Directs the output of cpio to file, instead of
                   the  standard  output.  If file is a character
                   special device and the current medium is full,
                   replace  the medium and type a carriage return
                   to continue to the next medium. Use only  with
                   the -o option.

     -P            Preserves ACLs. If the option is used for out-
                   put,  existing  ACLs  are  written  along with
                   other attributes, except for  extended  attri-
                   butes,   to  the  standard  output.  ACLs  are
                   created as special files with a  special  file
                   type.  If the option is used for input, exist-
                   ing ACLs are extracted along with other attri-
                   butes  from  standard input. The option recog-
                   nizes  the  special  file  type.  Notice  that
                   errors  will occur if a cpio archive with ACLs
                   is extracted by  previous  versions  of  cpio.
                   This  option  should  not  be used with the -c
                   option, as ACL support may not be  present  on
                   all  systems,  and  hence is not portable. Use
                   ASCII headers for portability.

     -r            Interactively renames files. If the user types
                   a  carriage return alone, the file is skipped.
                   If the user types a ``.'', the original  path-
                   name will be retained. Not available with cpio

     -R id         Reassigns ownership and group information  for
                   each  file  to  user  ID.  (ID must be a valid
                   login ID from  /etc/passwd.)  This  option  is
                   valid only for the super-user.

     -s            Swaps bytes within each half word.

     -S            Swaps halfwords within each word.

     -t            Prints a table of contents of  the  input.  If
                   any file in the table of contents has extended
                   attributes, these are also  listed.  No  files
                   are created. -t and -V are mutually exclusive.

     -u            Copies  unconditionally.  Normally,  an  older
                   file  will  not  replace a newer file with the
                   same name, although an  older  directory  will
                   update a newer directory.

     -v            Verbose. Prints a list of  file  and  extended
                   attribute names. When used with the -t option,
                   the table of contents looks like the output of
                   an ls -l command (see ls(1)).

     -V            Special verbose. Prints a dot  for  each  file
                   read  or  written.  Useful  to assure the user
                   that cpio is working without printing out  all
                   file names.

     -6            Processes a UNIX System Sixth Edition  archive
                   format file. Use only with the -i option. This
                   option is mutually exclusive with -c and -H.

     -@            Includes extended attributes  in  archive.  By
                   default,  cpio  does not place extended attri-
                   butes in the archive.  With  this  flag,  cpio
                   will look for extended attributes on the files
                   to be placed in the archive and add  them,  as
                   regular  files,  to  the archive. The extended
                   attribute files go in the archive  as  special
                   files  with  special  file  types. When the -@
                   flag is used with -i or -p, it instructs  cpio
                   to  restore extended attribute data along with
                   the normal file data. Extended attribute files
                   can  only be extracted from an archive as part
                   of a normal file extract. Attempts  to  expli-
                   citly extract attribute records are ignored.

     The following operands are supported:

     directory    A path name of an existing directory to be used
                  as the target of cpio -p.

     pattern      Expressions making use  of  a  pattern-matching
                  notation similar to that used by the shell (see
                  sh(1)) for filename pattern matching, and simi-
                  lar to regular expressions. The following meta-
                  characters are defined:

                  *        Matches  any  string,  including   the
                           empty string.

                  ?        Matches any single character.

                  [...]    Matches any one of the enclosed  char-
                           acters. A pair of characters separated
                           by `-' matches any symbol between  the
                           pair  (inclusive),  as  defined by the
                           system default collating sequence.  If
                           the   first  character  following  the
                           opening `[' is a `!', the results  are

                  !        The ! (exclamation point)  means  not.
                           For  example,  the !abc* pattern would
                           exclude all files that begin with abc.

                  In pattern,  metacharacters  ?,  *,  and  [...]
                  match  the  slash  (/) character, and backslash
                  (\) is an escape character.  Multiple cases  of
                  pattern  can  be specified and if no pattern is
                  specified, the default for pattern is  *  (that
                  is, select all files).

                  Each pattern must be enclosed in double quotes.
                  Otherwise,  the  name  of a file in the current
                  directory might be used.

     See largefile(5) for the description of the behavior of cpio
     when  encountering  files greater than or equal to 2 Gbyte (
     2^31 bytes).

     The following examples show three uses of cpio.

     Example 1 Using standard input

       example% ls | cpio -oc > ../newfile

     When standard input is directed through a pipe to  cpio  -o,
     as  in the example above, it groups the files so they can be
     directed (>) to a single file (../newfile).  The  -c  option
     insures that the file will be portable to other machines (as
     would the -H  option).  Instead  of  ls(1),  you  could  use
     find(1), echo(1), cat(1), and so on, to pipe a list of names
     to cpio. You could direct the output to a device instead  of
     a file.

     Example 2 Extracting files into directories

       example% cat newfile | cpio -icd "memo/a1" "memo/b*"

     In this example, cpio -i uses the output  file  of  cpio  -o
     (directed  through  a  pipe  with cat), extracts those files
     that match the patterns (memo/a1, memo/b*),  creates  direc-
     tories  below  the  current directory as needed (-d option),
     and places the files in the appropriate directories. The  -c
     option is used if the input file was created with a portable
     header. If no patterns were given, all  files  from  newfile
     would be placed in the directory.

     Example 3 Copying or linking files to another directory

       example% find . -depth -print | cpio -pdlmv newdir

     In this example, cpio -p takes the file names  piped  to  it
     and  copies  or  links  (-l  option)  those files to another
     directory, newdir. The -d option says to create  directories
     as  needed.  The  -m  option says to retain the modification
     time. (It is important to use the -depth option  of  find(1)
     to  generate  path  names for cpio. This eliminates problems
     that cpio could have trying to create files under  read-only
     directories.) The destination directory, newdir, must exist.

     Notice that when you use cpio in conjunction with  find,  if
     you  use  the  -L option with cpio, you must use the -follow
     option with find and vice versa. Otherwise,  there  will  be
     undesirable results.

     For multi-reel archives, dismount the old volume, mount  the
     new one, and continue to the next tape by typing the name of
     the next device (probably the same as the  first  reel).  To
     stop, type a RETURN and cpio will end.

     See environ(5) for descriptions of the following environment
     variables  that  affect  the  execution of cpio: LC_COLLATE,

     TMPDIR    cpio creates its temporary  file  in  /var/tmp  by
               default.  Otherwise,  it uses the directory speci-
               fied by TMPDIR.

     The following exit values are returned:

     0     Successful completion.

     >0    An error occurred.

     See attributes(5) for descriptions of the  following  attri-

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Availability                | SUNWcsu                     |
    | CSI                         | Enabled                     |
    | Interface Stability         | Stable                      |

     ar(1), cat(1), echo(1), find(1), ls(1), pax(1),  setfacl(1),
     sh(  1), tar(1), vold(1M), archives.h(3HEAD), attributes(5),
     environ(5), fsattr(5), largefile(5), standards(5)

     The maximum path name length allowed in a  cpio  archive  is
     determined  by the header type involved. The following table
     shows the proper value for  each  supported  archive  header

        Header type       Command line options   Maximum path name length
     BINARY               "-o"                   256
     POSIX                "-oH odc"              256
     ASCII                "-oc"                  1023
     CRC                  "-oH crc"              1023
     USTAR                "-oH ustar"            255

     When the command line options "-o -H tar" are specified, the
     archive  created  is of type USTAR. This means that it is an
     error to read this  same  archive  using  the  command  line
     options  "-i  -H  tar". The archive should be read using the
     command line options "-i -H ustar". The options "-i -H  tar"
     refer to an older tar archive format.

     An error message is output for files whose UID  or  GID  are
     too  large  to fit in the selected header format. Use -H crc
     or -c to create archives that allow all UID or GID values.

     Only the super-user can copy special files.

     Blocks are reported in 512-byte quantities.

     If a file has 000 permissions, contains more than 0  charac-
     ters of data, and the user is not root, the file will not be
     saved or restored.

     The    inode     number     stored     in     the     header
     (/usr/include/archives.h)  is  an unsigned short, which is 2
     bytes. This limits the range of  inode  numbers  from  0  to
     65535.  Files  which are hard linked must fall in this inode
     range. This could be a problem  when  moving  cpio  archives
     between different vendors' machines.

     When the Volume Management daemon is  running,  accesses  to
     floppy  devices  through  the conventional device names (for
     example, /dev/rdiskette) may not succeed. See  vold(1M)  for
     further details.

     You must use the same blocking factor when you  retrieve  or
     copy  files  from  the tape to the hard disk as you did when
     you copied files from the hard disk to the tape.  Therefore,
     you must specify the -B or -C option.

     During -p and -o processing,  cpio  buffers  the  file  list
     presented on stdin in a temporary file.

     The new pax(1) format, with a command that supports it  (for
     example,  pax  ,  tar,  or  cpio),  should be used for large
     files. The cpio command is no longer  part  of  the  current
     POSIX standard and is deprecated in favor of pax.

Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.