unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

cpio(1)                          User Commands                         cpio(1)



NAME
       cpio - copy file archives in and out

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

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

       cpio -p [-adlLmPuvV@] [-R id] directory

DESCRIPTION
       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 patterns are selected. See sh(1) and
       OPERANDS for more information about pattern. Extracted files are condi-
       tionally  copied  into the current directory tree, based on the options
       described below. The permissions of the files will be those of the pre-
       vious cpio -o command. The owner and group will be the same as the cur-
       rent 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 pre-
       vious 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 output, 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 below.

       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 fol-
       lowing message:

       To continue, type device/file name when ready.

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

OPTIONS
       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 speci-
                       fied.



       -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 sup-
                       ported  on  SVR4-based systems. When transferring files
                       between SunOS 4 or Interactive UNIX and the Solaris 2.6
                       Operating  environment  or  compatible versions, 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  file-
                       name per line).



       -f              Copies in all files except those in patterns. See OPER-
                       ANDS 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  num-
                                       bers  and an additional per-file check-
                                       sum. There are no UID or  GID  restric-
                                       tions  associated with this header for-
                                       mat.



                       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  offi-
                                       cial   format  for  transferring  files
                                       between POSIX-conforming  systems  (see
                                       standards(5)).  Use this format to com-
                                       municate 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  format  with
                                       option -o has the same effect as speci-
                                       fying the "ustar"  format:  the  output
                                       archive is in ustar format, and must be
                                       read using -H ustar.



                       ustar | USTAR   IEEE/P1003  Data  Interchange  Standard
                                       tar header and format. This header for-
                                       mat 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  completely
                       read, replace the medium and press <&lt;RETURN>&gt; 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  head-
                       ers.  For  cpio  archives  that  contain other cpio ar-
                       chives, 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 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, ar-
                       chives 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 spe-
                       cial device, you can use this option to define the mes-
                       sage  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 output.
                       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 portability.



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



       -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
                       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 mutu-
                       ally 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 explic-
                       itly extract attribute records are ignored.



OPERANDS
       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 file-
                       name  pattern  matching, and similar to regular expres-
                       sions. 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 unspeci-
                                fied.



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


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

EXAMPLES
       The following examples show three uses of cpio.

       Example 1: Using standard input

       example% ls | cpio -oc >&gt; ../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 directories below the current directory  as
       needed  (-d  option),  and places the files in the appropriate directo-
       ries. The -c option is used if the input file was created with a porta-
       ble  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 directo-
       ries.) 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  <&lt;RETURN>&gt;  and
       cpio will end.

ENVIRONMENT VARIABLES
       See  environ(5) for descriptions of the following environment variables
       that affect the execution of cpio: LC_COLLATE,  LC_CTYPE,  LC_MESSAGES,
       LC_TIME, TZ, and NLSPATH.

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



EXIT STATUS
       The following exit values are returned:

       0        Successful completion.



       >&gt;0       An error occurred.



ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).    ATTRIBUTE   TYPEATTRIBUTE  VALUE  AvailabilitySUNWcsu
       CSIEnabled Interface StabilityStable


SEE ALSO
       ar(1), cat(1), echo(1), find(1), ls(1),  pax(1),  setfacl(1),  sh(  1),
       tar(1),  vold(1M),  archives(4),  attributes(5), environ(5), fsattr(5),
       largefile(5), standards(5)

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


       tab(); lw(1.833333i) lw(1.833333i) lw(1.833333i).   Header  typeCommand
       line  optionsMaximum  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 characters 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  num-
       bers  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.



SunOS 5.10                        12 Mar 2004                          cpio(1)