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 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 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 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 in-
	     put 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  op-
	     tion.  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	unpre-

       -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 im-
	     plies  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 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 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

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

	     odc   ASCII  header  with	small  device  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  transferring
		   files  between POSIX-conforming systems (see	standards(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 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 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, us-
	     tar|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	 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	termi-
	     nate  prematurely.	cpio will find the next	good header, which may
	     be	one for	a smaller archive, and terminate when the smaller  ar-
	     chive'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.	Other-
	     wise, 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 en-
	     countered,	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  ineffec-
	     tive 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 out-
	     put. If file is a character special device	and the	current	medium
	     is	 full,	replace	 the medium and	type a carriage	return to con-
	     tinue 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 at-
	     tributes, 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  ex-
	     tracted  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	porta-

       -r    Interactively renames files. If the user types a carriage	return
	     alone, the	file is	skipped. If the	user types a ``.'', the	origi-
	     nal 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  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. Use-
	     ful 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	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  ex-
	     tracted  from  an	archive	 as part of a normal file extract. At-
	     tempts to explicitly extract attribute records are	ignored.

       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 char-
		   acters 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 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 (/) charac-
       ter, and	backslash (\) is an escape character. Multiple cases  of  pat-
       tern  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 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.

	     cpio  creates  its	 temporary file	in /var/tmp by default.	Other-
	     wise, 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),	setfacl(1),  sh(  1),  tar(1),
       vold(1M),  archives(4),	attributes(5),	environ(5),  fsattr(5),	large-
       file(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.

SunOS 5.9			  22 Oct 2001			       cpio(1)


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

home | help