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

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

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

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

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

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

       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