cpio man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

CPIO(1)								       CPIO(1)

NAME
       cpio - copy file archives in and out

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

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

       cpio -p [-adlLmPquvV@/] [-R id] directory

DESCRIPTION
       The  cpio command copies files into and out of a cpio archive. The cpio
       archive can 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 are those of the previous
       cpio -o command. The owner and group are the same as the current	 user,
       unless  the  current user has the {PRIV_FILE_CHOWN_SELF} privilege. See
       chown(2). If this is the case, owner and group are 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 outputs a warning message and not
       replace the file. The -u option can be used  to	unconditionally	 over‐
       write 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.

       If the underlying file system of the source file supports detection  of
       holes  as  reported  by pathconf(2), the file is a sparse file, and the
       destination file is seekable, then holes in sparse files are  preserved
       in pass mode, otherwise holes are filled with zeros.

       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 RETURN. You might
       want to continue by directing cpio to use a different device. For exam‐
       ple,  if	 you  have  two floppy drives you might want to switch between
       them so cpio can proceed while you are  changing	 the  floppies.	 Press
       RETURN to cause the cpio process to exit.

OPTIONS
       The following options are supported:

       -i
	     (copy in) Reads an archive from the standard input and condition‐
	     ally 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 standard input
	     and conditionally copies those files into the destination	direc‐
	     tory 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 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 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 envi‐
		     ronment 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 filename
		     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 ar‐
				      chive is in ustar format,	 and  must  be
				      read using -H ustar.

		     ustar | 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  are	 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  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 might 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  can  terminate  prematurely.
		     cpio  finds  the next good header, which can 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 is to the file referred to by
		     the symbolic link. Otherwise, the hard  link  is  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
		     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 stan‐
		     dard 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, exist‐
		     ing 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 occurs 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 might not  be  present
		     on	 all  systems,	and  hence  is not portable. Use ASCII
		     headers for portability.

       -q
		     Quiet. Suppresses the number of blocks message that  nor‐
		     mally is printed after the copy is completed.

       -r
		     Interactively renames files. If the user types a carriage
		     return alone, the file is skipped. If the	user  types  a
		     ``.'',  the original pathname is 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 the passwd
		     database.) This option is	valid  only  when  id  is  the
		     invoking user or the super-user. See NOTES.

       -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  is  not
		     replaced  a  newer	 file  with the same name, although an
		     older directory updates a newer directory.

       -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 writ‐
		     ten. Useful to assure the user that cpio is working with‐
		     out 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	looks  for  extended attributes on the
		     files to be placed in the archive and add them, as	 regu‐
		     lar  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 ignored.

       -/
		     Includes  extended	 system	 attributes  in	 archive.   By
		     default,  cpio  does not place extended system attributes
		     in the archive. With this flag, cpio looks	 for  extended
		     system  attributes	 on  the files to be placed in the ar‐
		     chive 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 sys‐
		     tem attribute data	 along	with  the  normal  file	 data.
		     Extended  system  attribute  files	 can only be extracted
		     from an  archive  as  part	 of  a	normal	file  extract.
		     Attempts  to  explicitly  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 sim‐
		    ilar 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 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	 char‐
		    acter.  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.

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 > ../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 is porta‐
       ble 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 are 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
       ends.

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. Oth‐
		 erwise, it uses the directory specified by TMPDIR.

EXIT STATUS
       The following exit values are returned:

       0
	     Successful completion.

       >0
	     An error occurred.

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │CSI		    │ Enabled	      │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Committed	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       ar(1), cat(1), echo(1),	find(1),  ls(1),  pax(1),  setfacl(1),	sh(1),
       tar(1),	 chown(2),   archives.h(3HEAD),	  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.

       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 characters of data,
       and the user is not root, the file is not saved or restored.

       When  cpio  is  invoked	in  Copy  In  or  Pass	Mode  by  a  user with
       {PRIV_FILE_CHOWN_SELF} privilege, and in particular on a	 system	 where
       {_POSIX_CHOWN_RESTRICTED}  is  not in effect (effectively granting this
       privilege to all users where not overridden), extracted or copied files
       can  end	 up with owners and groups determined by those of the original
       archived files, which can differ from the invoking user's.  This	 might
       not be what the user intended. The -R option can be used to retain file
       ownership, if desired, if you specify the user's id.

       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.

       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,
       tar),  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.

				  Aug 3, 2009			       CPIO(1)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net