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

   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
	     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	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
	     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 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
		   associated 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,
	     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	 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
	     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  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
	     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	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
	     extracted from an archive as  part	 of  a	normal	file  extract.
	     Attempts 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
		   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 (/)  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
       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

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

       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