cpio - copy file archives in and out


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

     cpio -o [-aABcLPvV@] [-C bufsize] [-H header] [  -O file  [-
     M message]]

     cpio -p [-adlLmPuvV@] [-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 invisible. Access
           times are not reset for linked files when cpio -pla is

     -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 portion 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 restric-
           tions 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  Interactive UNIX and the
           Solaris 2.6 Operating environment or  compatible  ver-
           sions, use -H odc.

     -C bufsize
           Blocks input/output bufsize bytes to the record, where
           bufsize is replaced by a positive 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 ori-
           gin and the destination machines are different  types.
           This  option is mutually exclusive with options -c and

           Valid values for header are:

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

                 ASCII header with expanded device numbers and an
                 additional  per-file  checksum. There are no UID
                 or GID restrictions associated with this  header

           odc   ASCII header with small device numbers. This  is
                 the  IEEE/P1003  Data  Interchange Standard cpio
                 header and format. It has the  widest  range  of
                 portability  of any of the header formats. It is
                 the  official  format  for  transferring   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 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  pro-
                 vided  for  the reading of legacy archives only,
                 that is, in conjunction with option -i.

                 Specifying this archive format  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.

                 IEEE/P1003 Data Interchange Standard tar  header
                 and  format.  This header format allows UIDs and
                 GIDs up to 2097151 to be stored in the header.

           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  com-
           pletely read, replace the medium and press <RETURN> to
           continue 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 corrupted 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 ter-
           minate 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 symbolic 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 direc-
           tory  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 link.

     -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  output,
           existing ACLs are written along with other attributes,
           except for extended attributes, to the  standard  out-
           put.  ACLs are created as special files with a special
           file type. If the option is used for  input,  existing
           ACLs  are  extracted  along with other attributes from
           standard input. The option recognizes 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 portabil-

     -r    Interactively renames files. If the user types a  car-
           riage  return  alone, the file is skipped. If the user
           types a ``.'', the original pathname will be retained.
           Not available with cpio -p.

     -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

     -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.

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

     -V    Special verbose. Prints a dot for each  file  read  or
           written.  Useful to assure the user that cpio is work-
           ing 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  attributes  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  explicitly extract attribute records are


     The following operands are supported:

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

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

           *     Matches any string, including the empty string.
           ?     Matches any single character.

           [...] Matches any one of the  enclosed  characters.  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 unspecified.

           !     The ! (exclamation point) means not.  For  exam-
                 ple,  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. Other-
           wise,  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,

           cpio  creates  its  temporary  file  in  /var/tmp   by
           default. Otherwise, it uses the directory specified by


     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), setfacl(1), sh(  1),
     tar(1),  vold(1M),  archives(4),  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.

Man(1) output converted with man2html