1PAX(1)                    BSD General Commands Manual                   PAX(1)
2

NAME

4     opax — read and write file archives and copy directory hierarchies (Open‐
5     BSD pax implementation)
6

SYNOPSIS

8     opax [-0cdOnvz] [-f archive] [-s replstr] ... [-U user] ... [-G group]
9          ... [-T [from_date] [,to_date]] ... [pattern ...]
10     opax -r [-cdiknuvzDOYZ] [-f archive] [-o options] ... [-p string] ...
11          [-s replstr] ... [-E limit] [-U user] ... [-G group] ... [-T
12          [from_date] [,to_date]] ... [pattern ...]
13     opax -w [-0dituvzHLOPX] [-b blocksize] [[-a] [-f archive]] [-x format]
14          [-s replstr] ... [-o options] ... [-U user] ... [-G group] ...
15          [-B bytes] [-T [from_date] [,to_date] [/[c][m]]] ... [file ...]
16     opax -r -w [-0diklntuvDHLOPXYZ] [-p string] ... [-s replstr] ...
17          [-U user] ... [-G group] ... [-T [from_date] [,to_date] [/[c][m]]]
18          ... [file ...] directory
19

DESCRIPTION

21     opax will read, write, and list the members of an archive file, and will
22     copy directory hierarchies.  opax operation is independent of the spe‐
23     cific archive format, and supports a wide variety of different archive
24     formats.  A list of supported archive formats can be found under the
25     description of the -x option.
26
27     The presence of the -r and the -w options specifies which of the follow‐
28     ing functional modes opax will operate under: list, read, write, and
29     copy.
30
31     <none>  List.  opax will write to standard output a table of contents of
32             the members of the archive file read from standard input, whose
33             pathnames match the specified patterns.  The table of contents
34             contains one filename per line and is written using single line
35             buffering.
36
37     -r      Read.  opax extracts the members of the archive file read from
38             the standard input, with pathnames matching the specified
39             patterns.  The archive format and blocking is automatically
40             determined on input.  When an extracted file is a directory, the
41             entire file hierarchy rooted at that directory is extracted.  All
42             extracted files are created relative to the current file hierar‐
43             chy.  The setting of ownership, access and modification times,
44             and file mode of the extracted files are discussed in more detail
45             under the -p option.
46
47     -w      Write.  opax writes an archive containing the file operands to
48             standard output using the specified archive format.  When no file
49             operands are specified, a list of files to copy with one per line
50             is read from standard input.  When a file operand is also a
51             directory, the entire file hierarchy rooted at that directory
52             will be included.
53
54     -r -w   Copy.  opax copies the file operands to the destination
55             directory.  When no file operands are specified, a list of files
56             to copy with one per line is read from the standard input.  When
57             a file operand is also a directory the entire file hierarchy
58             rooted at that directory will be included.  The effect of the
59             copy is as if the copied files were written to an archive file
60             and then subsequently extracted, except that there may be hard
61             links between the original and the copied files (see the -l
62             option below).
63
64             Warning: The destination directory must not be one of the file
65             operands or a member of a file hierarchy rooted at one of the
66             file operands.  The result of a copy under these conditions is
67             unpredictable.
68
69     While processing a damaged archive during a read or list operation, opax
70     will attempt to recover from media defects and will search through the
71     archive to locate and process the largest number of archive members pos‐
72     sible (see the -E option for more details on error handling).
73
74     The directory operand specifies a destination directory pathname.  If the
75     directory operand does not exist, or it is not writable by the user, or
76     it is not of type directory, opax will exit with a non-zero exit status.
77
78     The pattern operand is used to select one or more pathnames of archive
79     members.  Archive members are selected using the pattern matching nota‐
80     tion described by fnmatch(3).  When the pattern operand is not supplied,
81     all members of the archive will be selected.  When a pattern matches a
82     directory, the entire file hierarchy rooted at that directory will be
83     selected.  When a pattern operand does not select at least one archive
84     member, opax will write these pattern operands in a diagnostic message to
85     standard error and then exit with a non-zero exit status.
86
87     The file operand specifies the pathname of a file to be copied or
88     archived.  When a file operand does not select at least one archive mem‐
89     ber, opax will write these file operand pathnames in a diagnostic message
90     to standard error and then exit with a non-zero exit status.
91
92     The options are as follows:
93
94     -r      Read an archive file from standard input and extract the speci‐
95             fied files.  If any intermediate directories are needed in order
96             to extract an archive member, these directories will be created
97             as if mkdir(2) was called with the bitwise inclusive OR of
98             S_IRWXU, S_IRWXG, and S_IRWXO as the mode argument.  When the
99             selected archive format supports the specification of linked
100             files and these files cannot be linked while the archive is being
101             extracted, opax will write a diagnostic message to standard error
102             and exit with a non-zero exit status at the completion of opera‐
103             tion.
104
105     -w      Write files to the standard output in the specified archive for‐
106             mat.  When no file operands are specified, standard input is read
107             for a list of pathnames with one per line without any leading or
108             trailing ⟨blanks⟩.
109
110     -a      Append files to the end of an archive that was previously writ‐
111             ten.  If an archive format is not specified with a -x option, the
112             format currently being used in the archive will be selected.  Any
113             attempt to append to an archive in a format different from the
114             format already used in the archive will cause opax to exit imme‐
115             diately with a non-zero exit status.  The blocking size used in
116             the archive volume where writing starts will continue to be used
117             for the remainder of that archive volume.
118
119             Warning: Many storage devices are not able to support the opera‐
120             tions necessary to perform an append operation.  Any attempt to
121             append to an archive stored on such a device may damage the ar‐
122             chive or have other unpredictable results.  Tape drives in par‐
123             ticular are more likely to not support an append operation.  An
124             archive stored in a regular file system file or on a disk device
125             will usually support an append operation.
126
127     -0      Use the NUL (‘\0’) character as a pathname terminator, instead of
128             newline (‘\n’).  This applies only to the pathnames read from
129             standard input in the write and copy modes, and to the pathnames
130             written to standard output in list mode.  This option is expected
131             to be used in concert with the -print0 function in find(1) or the
132             -0 flag in xargs(1).
133
134     -b blocksize
135             When writing an archive, block the output at a positive decimal
136             integer number of bytes per write to the archive file.  The
137             blocksize must be a multiple of 512 bytes with a maximum of 64512
138             bytes.  Archives larger than 32256 bytes violate the POSIX stan‐
139             dard and will not be portable to all systems.  A blocksize can
140             end with ‘k’ or ‘b’ to specify multiplication by 1024 (1K) or
141             512, respectively.  A pair of blocksizes can be separated by ‘x’
142             to indicate a product.  A specific archive device may impose
143             additional restrictions on the size of blocking it will support.
144             When blocking is not specified, the default blocksize is depen‐
145             dent on the specific archive format being used (see the -x
146             option).
147
148     -c      Match all file or archive members except those specified by the
149             pattern and file operands.
150
151     -d      Cause files of type directory being copied or archived, or ar‐
152             chive members of type directory being extracted, to match only
153             the directory file or archive member and not the file hierarchy
154             rooted at the directory.
155
156     -f archive
157             Specify archive as the pathname of the input or output archive,
158             overriding the default standard input (for list and read) or
159             standard output (for write).  A single archive may span multiple
160             files and different archive devices.  When required, opax will
161             prompt for the pathname of the file or device of the next volume
162             in the archive.
163
164     -i      Interactively rename files or archive members.  For each archive
165             member matching a pattern operand or each file matching a file
166             operand, opax will prompt to /dev/tty giving the name of the
167             file, its file mode, and its modification time.  opax will then
168             read a line from /dev/tty.  If this line is blank, the file or
169             archive member is skipped.  If this line consists of a single
170             period, the file or archive member is processed with no modifica‐
171             tion to its name.  Otherwise, its name is replaced with the con‐
172             tents of the line.  opax will immediately exit with a non-zero
173             exit status if EOF is encountered when reading a response or if
174             /dev/tty cannot be opened for reading and writing.
175
176     -k      Do not overwrite existing files.
177
178     -l      (The lowercase letter “ell.”) Link files.  In the copy mode (-r
179             -w), hard links are made between the source and destination file
180             hierarchies whenever possible.
181
182     -n      Select the first archive member that matches each pattern oper‐
183             and.  No more than one archive member is matched for each
184             pattern.  When members of type directory are matched, the file
185             hierarchy rooted at that directory is also matched (unless -d is
186             also specified).
187
188     -o options
189             Information to modify the algorithm for extracting or writing ar‐
190             chive files which is specific to the archive format specified by
191             -x.  In general, options take the form: name=value.
192
193     -p string
194             Specify one or more file characteristic options (privileges).
195             The string option-argument is a string specifying file character‐
196             istics to be retained or discarded on extraction.  The string
197             consists of the specification characters a, e, m, o, and p.  Mul‐
198             tiple characteristics can be concatenated within the same string
199             and multiple -p options can be specified.  The meaning of the
200             specification characters are as follows:
201
202             a   Do not preserve file access times.  By default, file access
203                 times are preserved whenever possible.
204
205             e   ‘Preserve everything’, the user ID, group ID, file mode bits,
206                 file access time, and file modification time.  This is
207                 intended to be used by root, someone with all the appropriate
208                 privileges, in order to preserve all aspects of the files as
209                 they are recorded in the archive.  The e flag is the sum of
210                 the o and p flags.
211
212             m   Do not preserve file modification times.  By default, file
213                 modification times are preserved whenever possible.
214
215             o   Preserve the user ID and group ID.
216
217             p   ‘Preserve’ the file mode bits.  This is intended to be used
218                 by a user with regular privileges who wants to preserve all
219                 aspects of the file other than the ownership.  The file times
220                 are preserved by default, but two other flags are offered to
221                 disable this and use the time of extraction instead.
222
223             In the preceding list, ‘preserve’ indicates that an attribute
224             stored in the archive is given to the extracted file, subject to
225             the permissions of the invoking process.  Otherwise the attribute
226             of the extracted file is determined as part of the normal file
227             creation action.  If neither the e nor the o specification char‐
228             acter is specified, or the user ID and group ID are not preserved
229             for any reason, opax will not set the S_ISUID (setuid) and
230             S_ISGID (setgid) bits of the file mode.  If the preservation of
231             any of these items fails for any reason, opax will write a diag‐
232             nostic message to standard error.  Failure to preserve these
233             items will affect the final exit status, but will not cause the
234             extracted file to be deleted.  If the file characteristic letters
235             in any of the string option-arguments are duplicated or conflict
236             with each other, the one(s) given last will take precedence.  For
237             example, if
238                   -p eme
239             is specified, file modification times are still preserved.
240
241     -s replstr
242             Modify the file or archive member names specified by the pattern
243             or file operands according to the substitution expression
244             replstr, using the syntax of the ed(1) utility regular expres‐
245             sions.  The format of these regular expressions are:
246                   /old/new/[gp]
247             As in ed(1), old is a basic regular expression and new can con‐
248             tain an ampersand (‘&’), ‘\n’ (where n is a digit) back-refer‐
249             ences, or subexpression matching.  The old string may also con‐
250             tain newline characters.  Any non-null character can be used as a
251             delimiter (‘/’ is shown here).  Multiple -s expressions can be
252             specified.  The expressions are applied in the order they are
253             specified on the command line, terminating with the first suc‐
254             cessful substitution.  The optional trailing g continues to apply
255             the substitution expression to the pathname substring which
256             starts with the first character following the end of the last
257             successful substitution.  The first unsuccessful substitution
258             stops the operation of the g option.  The optional trailing p
259             will cause the final result of a successful substitution to be
260             written to standard error in the following format:
261                   <original pathname> >> <new pathname>
262             File or archive member names that substitute to the empty string
263             are not selected and will be skipped.
264
265     -t      Reset the access times of any file or directory read or accessed
266             by opax to be the same as they were before being read or accessed
267             by opax.
268
269     -u      Ignore files that are older (having a less recent file modifica‐
270             tion time) than a pre-existing file or archive member with the
271             same name.  During read, an archive member with the same name as
272             a file in the file system will be extracted if the archive member
273             is newer than the file.  During write, a file system member with
274             the same name as an archive member will be written to the archive
275             if it is newer than the archive member.  During copy, the file in
276             the destination hierarchy is replaced by the file in the source
277             hierarchy or by a link to the file in the source hierarchy if the
278             file in the source hierarchy is newer.
279
280     -v      During a list operation, produce a verbose table of contents
281             using the format of the ls(1) utility with the -l option.  For
282             pathnames representing a hard link to a previous member of the
283             archive, the output has the format:
284                   <ls -l listing> == <link name>
285             For pathnames representing a symbolic link, the output has the
286             format:
287                   <ls -l listing> => <link name>
288             Where <ls -l listing> is the output format specified by the ls(1)
289             utility when used with the -l option.  Otherwise for all the
290             other operational modes (read, write, and copy), pathnames are
291             written and flushed to standard error without a trailing newline
292             as soon as processing begins on that file or archive member.  The
293             trailing newline is not buffered and is written only after the
294             file has been read or written.
295
296     -x format
297             Specify the output archive format, with the default format being
298             ustar.  opax currently supports the following formats:
299
300             cpio     The extended cpio interchange format specified in the
301                      IEEE Std 1003.2 (“POSIX.2”) standard.  The default
302                      blocksize for this format is 5120 bytes.  Inode and
303                      device information about a file (used for detecting file
304                      hard links by this format) which may be truncated by
305                      this format is detected by opax and is repaired.
306
307             bcpio    The old binary cpio format.  The default blocksize for
308                      this format is 5120 bytes.  This format is not very por‐
309                      table and should not be used when other formats are
310                      available.  Inode and device information about a file
311                      (used for detecting file hard links by this format)
312                      which may be truncated by this format is detected by
313                      opax and is repaired.
314
315             sv4cpio  The System V release 4 cpio.  The default blocksize for
316                      this format is 5120 bytes.  Inode and device information
317                      about a file (used for detecting file hard links by this
318                      format) which may be truncated by this format is
319                      detected by opax and is repaired.
320
321             sv4crc   The System V release 4 cpio with file crc checksums.
322                      The default blocksize for this format is 5120 bytes.
323                      Inode and device information about a file (used for
324                      detecting file hard links by this format) which may be
325                      truncated by this format is detected by opax and is
326                      repaired.
327
328             tar      The old BSD tar format as found in BSD4.3.  The default
329                      blocksize for this format is 10240 bytes.  Pathnames
330                      stored by this format must be 100 characters or less in
331                      length (including the trailing   character, which means
332                      that filenames can have a maximum length of 99 charac‐
333                      ters).  Only regular files, hard links, soft links, and
334                      directories will be archived (other file system types
335                      are not supported).  For backwards compatibility with
336                      even older tar formats, a -o option can be used when
337                      writing an archive to omit the storage of directories.
338                      This option takes the form:
339                            -o write_opt=nodir
340
341             ustar    The extended tar interchange format specified in the
342                      IEEE Std 1003.2 (“POSIX.2”) standard.  The default
343                      blocksize for this format is 10240 bytes.  Filenames
344                      stored by this format must be 100 characters or less in
345                      length (including the trailing   character, which means
346                      that filenames can have a maximum length of 99 charac‐
347                      ters).  Pathnames (directorynames + filenames) stored by
348                      this format must be 250 characters or less in length.
349
350             opax will detect and report any file that it is unable to store
351             or extract as the result of any specific archive format restric‐
352             tions.  The individual archive formats may impose additional
353             restrictions on use.  Typical archive format restrictions include
354             (but are not limited to): file pathname length, file size, link
355             pathname length, and the type of the file.
356
357     -z      Use gzip(1) to compress (decompress) the archive while writing
358             (reading).  Incompatible with -a.
359
360     -B bytes
361             Limit the number of bytes written to a single archive volume to
362             bytes.  The bytes limit can end with ‘m’, ‘k’, or ‘b’ to specify
363             multiplication by 1048576 (1M), 1024 (1K) or 512, respectively.
364             A pair of bytes limits can be separated by ‘x’ to indicate a
365             product.
366
367             Warning: Only use this option when writing an archive to a device
368             which supports an end of file read condition based on last (or
369             largest) write offset (such as a regular file or a tape drive).
370             The use of this option with a floppy or hard disk is not recom‐
371             mended.
372
373     -D      This option is the same as the -u option, except that the file
374             inode change time is checked instead of the file modification
375             time.  The file inode change time can be used to select files
376             whose inode information (e.g., UID, GID, etc.) is newer than a
377             copy of the file in the destination directory.
378
379     -E limit
380             Limit the number of consecutive read faults while trying to read
381             a flawed archive to limit.  With a positive limit, opax will
382             attempt to recover from an archive read error and will continue
383             processing starting with the next file stored in the archive.  A
384             limit of 0 will cause opax to stop operation after the first read
385             error is detected on an archive volume.  A limit of NONE will
386             cause opax to attempt to recover from read errors forever.  The
387             default limit is a small positive number of retries.
388
389             Warning: Using this option with NONE should be used with extreme
390             caution as opax may get stuck in an infinite loop on a very badly
391             flawed archive.
392
393     -G group
394             Select a file based on its group name, or when starting with a #,
395             a numeric gid.  A ‘\’ can be used to escape the #.  Multiple -G
396             options may be supplied and checking stops with the first match.
397
398     -H      Follow only command-line symbolic links while performing a physi‐
399             cal file system traversal.
400
401     -L      Follow all symbolic links to perform a logical file system tra‐
402             versal.
403
404     -O      Force the archive to be one volume.  If a volume ends prema‐
405             turely, opax will not prompt for a new volume.  This option can
406             be useful for automated tasks where error recovery cannot be per‐
407             formed by a human.
408
409     -P      Do not follow symbolic links, perform a physical file system tra‐
410             versal.  This is the default mode.
411
412     -T [from_date][,to_date][/[c][m]]
413             Allow files to be selected based on a file modification or inode
414             change time falling within a specified time range of from_date to
415             to_date (the dates are inclusive).  If only a from_date is sup‐
416             plied, all files with a modification or inode change time equal
417             to or younger are selected.  If only a to_date is supplied, all
418             files with a modification or inode change time equal to or older
419             will be selected.  When the from_date is equal to the to_date,
420             only files with a modification or inode change time of exactly
421             that time will be selected.
422
423             When opax is in the write or copy mode, the optional trailing
424             field [c][m] can be used to determine which file time (inode
425             change, file modification or both) are used in the comparison.
426             If neither is specified, the default is to use file modification
427             time only.  The m specifies the comparison of file modification
428             time (the time when the file was last written).  The c specifies
429             the comparison of inode change time (the time when the file inode
430             was last changed; e.g., a change of owner, group, mode, etc).
431             When c and m are both specified, then the modification and inode
432             change times are both compared.  The inode change time comparison
433             is useful in selecting files whose attributes were recently
434             changed or selecting files which were recently created and had
435             their modification time reset to an older time (as what happens
436             when a file is extracted from an archive and the modification
437             time is preserved).  Time comparisons using both file times is
438             useful when opax is used to create a time based incremental ar‐
439             chive (only files that were changed during a specified time range
440             will be archived).
441
442             A time range is made up of six different fields and each field
443             must contain two digits.  The format is:
444                   [[[[[cc]yy]mm]dd]HH]MM[.SS]
445             Where cc is the first two digits of the year (the century), yy is
446             the last two digits of the year, the first mm is the month (from
447             01 to 12), dd is the day of the month (from 01 to 31), HH is the
448             hour of the day (from 00 to 23), MM is the minute (from 00 to
449             59), and SS is the seconds (from 00 to 59).  The minute field MM
450             is required, while the other fields are optional and must be
451             added in the following order:
452                  HH, dd, mm, yy, cc.
453             The SS field may be added independently of the other fields.
454             Time ranges are relative to the current time, so
455                   -T 1234/cm
456             would select all files with a modification or inode change time
457             of 12:34 PM today or later.  Multiple -T time range can be sup‐
458             plied and checking stops with the first match.
459
460     -U user
461             Select a file based on its user name, or when starting with a #,
462             a numeric UID.  A ‘\’ can be used to escape the #.  Multiple -U
463             options may be supplied and checking stops with the first match.
464
465     -X      When traversing the file hierarchy specified by a pathname, do
466             not descend into directories that have a different device ID.
467             See the st_dev field as described in stat(2) for more information
468             about device IDs.
469
470     -Y      This option is the same as the -D option, except that the inode
471             change time is checked using the pathname created after all the
472             file name modifications have completed.
473
474     -Z      This option is the same as the -u option, except that the modifi‐
475             cation time is checked using the pathname created after all the
476             file name modifications have completed.
477
478     The options that operate on the names of files or archive members (-c,
479     -i, -n, -s, -u, -v, -D, -G, -T, -U, -Y, and -Z) interact as follows.
480
481     When extracting files during a read operation, archive members are
482     ‘selected’, based only on the user specified pattern operands as modified
483     by the -c, -n, -u, -D, -G, -T, -U options.  Then any -s and -i options
484     will modify in that order, the names of these selected files.  Then the
485     -Y and -Z options will be applied based on the final pathname.  Finally,
486     the -v option will write the names resulting from these modifications.
487
488     When archiving files during a write operation, or copying files during a
489     copy operation, archive members are ‘selected’, based only on the user
490     specified pathnames as modified by the -n, -u, -D, -G, -T, and -U options
491     (the -D option only applies during a copy operation).  Then any -s and -i
492     options will modify in that order, the names of these selected files.
493     Then during a copy operation the -Y and the -Z options will be applied
494     based on the final pathname.  Finally, the -v option will write the names
495     resulting from these modifications.
496
497     When one or both of the -u or -D options are specified along with the -n
498     option, a file is not considered selected unless it is newer than the
499     file to which it is compared.
500

ENVIRONMENT

502     TMPDIR      Path in which to store temporary files.
503

EXAMPLES

505     $ opax -w -f /dev/rst0 .
506
507     Copies the contents of the current directory to the device /dev/rst0.
508
509     $ opax -v -f filename
510
511     Gives the verbose table of contents for an archive stored in filename.
512
513     $ mkdir newdir; cd olddir; opax -rw . newdir
514
515     This sequence of commands will copy the entire olddir directory hierarchy
516     to newdir.
517
518     $ opax -r -s ',^//*usr//*,,' -f a.pax
519
520     Reads the archive a.pax, with all files rooted in /usr into the archive
521     extracted relative to the current directory.
522
523     $ opax -rw -i . dest_dir
524
525     Can be used to interactively select the files to copy from the current
526     directory to dest_dir.
527
528     $ opax -r -pe -U root -G bin -f a.pax
529
530     Extract all files from the archive a.pax which are owned by root with
531     group bin and preserve all file permissions.
532
533     $ opax -r -w -v -Y -Z home /backup"
534
535     Update (and list) only those files in the destination directory /backup
536     which are older (less recent inode change or file modification times)
537     than files with the same name found in the source file tree home.
538

DIAGNOSTICS

540     opax will exit with one of the following values:
541
542     0   All files were processed successfully.
543
544     1   An error occurred.
545
546     Whenever opax cannot create a file or a link when reading an archive or
547     cannot find a file when writing an archive, or cannot preserve the user
548     ID, group ID, or file mode when the -p option is specified, a diagnostic
549     message is written to standard error and a non-zero exit status will be
550     returned, but processing will continue.  In the case where opax cannot
551     create a link to a file, opax will not create a second copy of the file.
552
553     If the extraction of a file from an archive is prematurely terminated by
554     a signal or error, opax may have only partially extracted a file the user
555     wanted.  Additionally, the file modes of extracted files and directories
556     may have incorrect file bits, and the modification and access times may
557     be wrong.
558
559     If the creation of an archive is prematurely terminated by a signal or
560     error, opax may have only partially created the archive which may violate
561     the specific archive format specification.
562
563     If while doing a copy, opax detects a file is about to overwrite itself,
564     the file is not copied, a diagnostic message is written to standard error
565     and when opax completes it will exit with a non-zero exit status.
566

SEE ALSO

568     spax(1), tar(1), bsdtar(1), star(1), cpio(1), bsdcpio(1), scpio(1)
569

STANDARDS

571     The opax utility is a superset of the IEEE Std 1003.2 (“POSIX.2”) stan‐
572     dard.  The options -B, -D, -E, -G, -H, -L, -O, -P, -T, -U, -Y, -Z, the
573     archive formats bcpio, sv4cpio, sv4crc, tar, and the flawed archive han‐
574     dling during list and read operations are extensions to the POSIX stan‐
575     dard.
576

AUTHORS

578     Keith Muller at the University of California, San Diego.
579
580BSD                             April 18, 1994                             BSD
Impressum