Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
cpio(1)				 User Commands			       cpio(1)

       cpio - copy file	archives in and	out

       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

       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 as-
       sumed 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 OPER-
       ANDS for	more information about pattern.	Extracted files	are condition-
       ally  copied  into the current directory	tree, based on the options de-
       scribed below. The permissions of the files will	be those of the	previ-
       ous  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

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

       -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  de-
		       fault  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 op-
		       tion 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 Operat-
		       ing 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-

		       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  be-
				       tween   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 op-
				       tion -o has the same effect as specify-
				       ing  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 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 <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 op-
		       tion  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	prema-
		       turely. 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

       -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,  ex-
		       isting  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. No-
		       tice 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-

       -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 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	attri-
		       bute files go in	the archive as special files with spe-
		       cial 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	attri-
		       bute  files  can	 only  be extracted from an archive as
		       part of a normal	file extract. Attempts	to  explicitly
		       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 file-
		       name pattern matching, and similar to  regular  expres-
		       sions. The following metacharacters are defined:

		       *	Matches	  any	string,	 including  the	 empty

		       ?	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 se-
				quence.	If the first character	following  the
				opening	`[' is a `!', the results are unspeci-

		       !	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  en-
       countering 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

       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  op-
       tion 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,	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.

       The following exit values are returned:

       0	Successful completion.

       >0	An error occurred.

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

       |      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(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 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  op-
       tions "-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 in-
       ode  range.  This  could	be a problem when moving cpio archives between
       different vendors' machines.

       When the	Volume Management daemon is running, accesses  to  floppy  de-
       vices   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 op-

       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)


Want to link to this manual page? Use this URL:

home | help