sys/src/ape/cmd/pax/cpio.1.man

   1 .\" $Id: cpio.1,v 1.2 89/02/12 10:08:42 mark Exp $
   2 .TH CPIO 1 "USENIX Association" ""
   3 .SH NAME
   4 cpio \- copy file archives in and out
   5 .SH SYNOPSIS
   6 .B cpio
   7 .BR \-o [ Bacv ]
   8 .br
   9 .B cpio
  10 .BR \-i [ Bcdfmrtuv ]
  11 .RI [ pattern... ]
  12 .br
  13 .B cpio
  14 .BR \-p [ adlmruv ]
  15 .I directory
  16 .SH DESCRIPTION
  17 The
  18 .B cpio
  19 utility produces and reads files in the format specified by the
  20 .B cpio
  21 .B "Archive/Interchange File Format"
  22 specified in
  23 .IR "IEEE Std. 1003.1-1988" .
  24 .PP
  25 The
  26 .B "cpio -i"
  27 (copy in) utility extracts files from the standard input, which is
  28 assumed to be the product of a previous
  29 .B "cpio -o" .
  30 Only files with names that match
  31 .I patterns
  32 are selected.
  33 Multiple
  34 .I patterns
  35 may be specified and if no
  36 .I patterns
  37 are specified, the default for
  38 .I patterns
  39 is \*, selecting all files.
  40 The extracted files are conditionally created and copied into the
  41 current directory, and possibly any levels below, based upon the
  42 options described below and the permissions of the files will be those
  43 of the previous
  44 .B "cpio -o" .
  45 The owner and group of the files will be that of the current user
  46 unless the user has appropriate privileges, which causes
  47 .B cpio
  48 to retains the owner and group of the files of the previous
  49 .B "cpio -o" .
  50 .PP
  51 The
  52 .B "cpio -p"
  53 (pass) utility reads the standard input to obtain a list of path names
  54 of files that are conditionally created and copied into the
  55 destination
  56 .I directory
  57 based upon the options described below.
  58 .PP
  59 If an error is detected, the cause is reported and the
  60 .B cpio
  61 utility will continue to copy other files.
  62 .B cpio
  63 will skip over any unrecognized files which it encounters in the archive.
  64 .PP
  65 The following restrictions apply to the
  66 .B cpio
  67 utility:
  68 .IP 1 .25i
  69 Pathnames are restricted to 256 characters.
  70 .IP 2 .25i
  71 Appropriate privileges are required to copy special files.
  72 .IP 3 .25i
  73 Blocks are reported in 512-byte quantities.
  74 .SS Options
  75 The following options are available:
  76 .TP .5i
  77 .B \-B
  78 Input/output is to be blocked 5120 bytes to the record.
  79 Can only be used with
  80 .B "cpio -o"
  81 or
  82 .B "cpio -i"
  83 for data that is directed to or from character special files.
  84 .TP .5i
  85 .B \-a
  86 Reset access times of input files after they have been copied.
  87 When the
  88 .B \-l
  89 option is also specified, the linked files do not have their access
  90 times reset.
  91 Can only be used with
  92 .B "cpio -o"
  93 or
  94 .B "cpio -i" .
  95 .TP .5i
  96 .B \-c
  97 Write header information in ASCII character for for portability.
  98 Can only be used with
  99 .B "cpio -i"
 100 or
 101 .B "cpio -o" .
 102 Note that this option should always be used to write portable files.
 103 .TP .5i
 104 .B \-d
 105 Creates directories as needed.
 106 Can only be used with
 107 .B "cpio -i"
 108 or
 109 .B "cpio -p" .
 110 .TP .5i
 111 .B \-f
 112 Copy in all files except those in
 113 .I patterns .
 114 Can only be used with
 115 .B "cpio -i" .
 116 .TP .5i
 117 .B \-l
 118 Whenever possible, link files rather than copying them.
 119 Can only be used with
 120 .B "cpio -p" .
 121 .TP .5i
 122 .B \-m
 123 Retain previous modification times.
 124 This option is ineffective on directories that are being copied.
 125 Can only be used with
 126 .B "cpio -i"
 127 or
 128 .B "cpio -p" .
 129 .TP .5i
 130 .B \-r
 131 Interactively rename files.
 132 The user is asked whether to rename
 133 .I pattern
 134 each invocation.
 135 Read and write permissions for
 136 .B "/dev/tty"
 137 are required for this option.
 138 If the user types a null line, the file is skipped.
 139 Should only be used with
 140 .B "cpio -i"
 141 or
 142 .B "cpio -o" .
 143 .TP .5i
 144 .B \-t
 145 Print a table of contents of the input.
 146 No files are created.
 147 Can only be used with
 148 .B "cpio -i" .
 149 .TP .5i
 150 .B \-u
 151 Copy files unconditionally; usually an older file will not replace a
 152 new file with the same name.
 153 Can only be used with
 154 .B "cpio -i"
 155 or
 156 .B "cpio -p" .
 157 .TP .5i
 158 .B \-v
 159 Verbose: cause the names of the affected files to be printed.
 160 Can only be used with
 161 .B "cpio -i" .
 162 Provides a detailed listing when used with the
 163 .B \-t
 164 option.
 165 .SS Operands
 166 The following operands are available:
 167 .TP 1i
 168 .I patterns
 169 Simple regular expressions given in the name-generating notation of the
 170 shell.
 171 .TP 1i
 172 .I directory
 173 The destination directory.
 174 .SS "Exit Status"
 175 The
 176 .B cpio
 177 utility exits with one of the following values:
 178 .TP .5i
 179 0
 180 All input files were copied.
 181 .TP .5i
 182 2
 183 The utility encountered errors in copying or accessing files or
 184 directories.
 185 An error will be reported for nonexistent files or directories, or
 186 permissions that do not allow the user to access the source or target
 187 files.
 188 .SS
 189 It is important to use the
 190 .B "-depth"
 191 option of the
 192 .B find
 193 utility to generate pathnames for
 194 .B cpio .
 195 This eliminates problems
 196 .B cpio
 197 could have trying to create files under read-only directories.
 198 .PP
 199 The following command:
 200 .RS
 201 ls | cpio -o > ../newfile
 202 .RE
 203 copies out the files listed by the
 204 .B ls
 205 utility and redirects them to the file
 206 .B newfile .
 207 .PP
 208 The following command:
 209 .RS
 210 cat newfile | cpio -id "memo/al" "memo/b*"
 211 .RE
 212 uses the output file
 213 .B newfile
 214 from the
 215 .B "cpio -o"
 216 utility, takes those files that match the patterns
 217 .B "memo/al"
 218 and
 219 .B "memo/b*" ,
 220 creates the directories below the current directory, and places the
 221 files in the appropriate directories.
 222 .PP
 223 The command
 224 .RS
 225 find . -depth -print | cpio -pdlmv newdir
 226 .RE
 227 takes the file names piped to it from the
 228 .B find
 229 utility and copies or links those files to another directory
 230 named
 231 .B newdir ,
 232 while retaining the modification time.
 233 .SH FILES
 234 .TP 1i
 235 /dev/tty
 236 used to prompt the user for information when the
 237 .B \-i
 238 or
 239 .B \-r
 240 options are specified.
 241 .SH "SEE ALSO"
 242 find(1), pax(1), tar(1), cpio(5), tar(5)
 243 .SH COPYRIGHT
 244 Copyright (c) 1989 Mark H. Colburn.
 245 .br
 246 All rights reserved.
 247 .PP
 248 Redistribution and use in source and binary forms are permitted
 249 provided that the above copyright notice is duplicated in all such
 250 forms and that any documentation, advertising materials, and other
 251 materials related to such distribution and use acknowledge that the
 252 software was developed by Mark H. Colburn and sponsored by The
 253 USENIX Association.
 254 .PP
 255 THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
 256 IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 257 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 258 .SH AUTHOR
 259 Mark H. Colburn
 260 .br
 261 NAPS International
 262 .br
 263 117 Mackubin Street, Suite 1
 264 .br
 265 St. Paul, MN 55102
 266 .br
 267 mark@jhereg.MN.ORG
 268 .sp 2
 269 Sponsored by
 270 .B "The USENIX Association"
 271 for public distribution.