.rn '' }`
''' $RCSfile$$Revision$$Date$
'''
''' $Log$
'''
.de Sh
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb
.ft CW
.nf
.ne \\$1
..
.de Ve
.ft R

.fi
..
'''
'''
'''     Set up \*(-- to give an unbreakable dash;
'''     string Tr holds user defined translation string.
'''     Bell System Logo is used as a dummy character.
'''
.tr \(*W-|\(bv\*(Tr
.ie n \{\
.ds -- \(*W-
.ds PI pi
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.ds L" ""
.ds R" ""
'''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
'''   \*(L" and \*(R", except that they are used on ".xx" lines,
'''   such as .IP and .SH, which do another additional levels of
'''   double-quote interpretation
.ds M" """
.ds S" """
.ds N" """""
.ds T" """""
.ds L' '
.ds R' '
.ds M' '
.ds S' '
.ds N' '
.ds T' '
'br\}
.el\{\
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds M" ``
.ds S" ''
.ds N" ``
.ds T" ''
.ds L' `
.ds R' '
.ds M' `
.ds S' '
.ds N' `
.ds T' '
.ds PI \(*p
'br\}
.\"	If the F register is turned on, we'll generate
.\"	index entries out stderr for the following things:
.\"		TH	Title 
.\"		SH	Header
.\"		Sh	Subsection 
.\"		Ip	Item
.\"		X<>	Xref  (embedded
.\"	Of course, you have to process the output yourself
.\"	in some meaninful fashion.
.if \nF \{
.de IX
.tm Index:\\$1\t\\n%\t"\\$2"
..
.nr % 0
.rr F
.\}
.TH ARCHIVE 1 "perl 5.005, patch 03" "31/Dec/2001" "User Contributed Perl Documentation"
.UC
.if n .hy 0
.if n .na
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.de CQ          \" put $1 in typewriter font
.ft CW
'if n "\c
'if t \\&\\$1\c
'if n \\&\\$1\c
'if n \&"
\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
'.ft R
..
.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
.	\" AM - accent mark definitions
.bd B 3
.	\" fudge factors for nroff and troff
.if n \{\
.	ds #H 0
.	ds #V .8m
.	ds #F .3m
.	ds #[ \f1
.	ds #] \fP
.\}
.if t \{\
.	ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.	ds #V .6m
.	ds #F 0
.	ds #[ \&
.	ds #] \&
.\}
.	\" simple accents for nroff and troff
.if n \{\
.	ds ' \&
.	ds ` \&
.	ds ^ \&
.	ds , \&
.	ds ~ ~
.	ds ? ?
.	ds ! !
.	ds /
.	ds q
.\}
.if t \{\
.	ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.	ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.	ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.	ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.	ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.	ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
.	ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
.	ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.	ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
.\}
.	\" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.ds oe o\h'-(\w'o'u*4/10)'e
.ds Oe O\h'-(\w'O'u*4/10)'E
.	\" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.	\" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.	ds : e
.	ds 8 ss
.	ds v \h'-1'\o'\(aa\(ga'
.	ds _ \h'-1'^
.	ds . \h'-1'.
.	ds 3 3
.	ds o a
.	ds d- d\h'-1'\(ga
.	ds D- D\h'-1'\(hy
.	ds th \o'bp'
.	ds Th \o'LP'
.	ds ae ae
.	ds Ae AE
.	ds oe oe
.	ds Oe OE
.\}
.rm #[ #] #H #V #F C
.SH "NAME"
\fBarchive\fR \- perform basic file-handling operations on the local
archival storage system.
.SH "SYNOPSIS"
\fBarchive\fR\ \fBput\fR\ [putopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \ \ \ \ \ \ \ \ \ \ \ \ \ 

\fBarchive\fR\ \fBget\fR\ [getopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \ \ \ \ \ \ \ \ \ \ \ \ \ 

\fBarchive\fR\ \fBmv\fR*\ [mvopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \fItarget\fR\ \ \ \ \ 

\fBarchive\fR\ \fBrm\fR*\ [rmopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 

\fBarchive\fR\ \fBls\fR\ [lsopts]\ [\fIfile1\ ...\fR]\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 

\fBarchive\fR\ \fBstat\fR\ [statopts]\ [\fIname\fR]\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 

\fBarchive\fR\ \fBmkdir\fR\ [mkdiropts]\ \fIdir1\fR\ [\fIdir2\ ...\fR]\ \ \ \ \ \ \ \ \ \ \ \ 

\fBarchive\fR\ \fBrmdir\fR*\ [rmdiropts]\ \fIdir1\fR\ [\fIdir2\ ...\fR]\ \ \ \ \ \ \ \ \ \ \ 

\fBarchive\fR\ \fBchmod\fR*\ [chmodopts]\ \fImode\fR\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ 

\fBarchive\fR\ \fBchgrp\fR*\ [chgrpopts]\ group\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \ \ 

\fBarchive\fR\ \fBchown\fR*\ [chownopts]\ owner[:group]\ [\fIfile1\ ...\fR]\ \ \ \ 

\fBarchive\fR\ \fBmigrate\fR*\ \-(M|u|q)\ [migrateopts]\ \fIfile1\fR\ \fIfile2\ ...\fR]\ 

.SH "DESCRIPTION"
\fBarchive\fR provides users with a uniform, site-independent command
interface to the local archival storage system, eliminating the need
to learn the myriad syntactical variations that appear at different
institutions to perform essentially identical archival file management
tasks.
.SH "COMMANDS"
Each instance of \fBarchive\fR performs the file-management command
identified by \fBarchive\fR's first argument: \fBput\fR, \fBget\fR, \fBmv\fR*,
\fBrm\fR*, \fBls\fR, \fBstat\fR, \fBmkdir\fR, \fBrmdir\fR*, \fBchmod\fR*, \fBchgrp\fR*, or
\fBchown\fR*.  Each command accepts a set of arguments as well as a
set of command-line options described in the \fBOPTIONS\fR section
below.  If multiple archival storage facilities are available at
a particular site, all of the commands act on the the default
system only, unless another system is specified with the
\fB\-asf\fR\ \fIhost\fR option.  The detailed behavior of the different
commands is as follows:

.PP
* The current version of \fBarchive\fR does not support the commands
indicated with asterisks (*).  Later versions will incorporate
these additional commands.
.Ip "\fBarchive\ put\fR\ [putopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]" 4

Copy files \fIfile1\fR [\fIfile2 ...\fR] from the current working
directory to the archival storage system.  Options \fIputopts\fR
include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR, \fB\-C\fR\ \fIpath\fR, \fB\-s\fR,
\fB\-f\fR, \fB\-i\fR, \fB\-p\fR, \fB\-M\fR, \fB\-D\fR, \fB\-n\fR, \fB\-t\fR\ \fItarfile\fR, \fB\-S\fR,
and \fB\-z\fR.  \fIfile1\fR [\fIfile2\ ...\fR] may contain wildcards * and ?.
.Sp
The destination
directory on the archival storage system may be specified using the
\fB\-C\fR\ \fIpath\fR option.  If \fB\-C\fR\ \fIpath\fR is not present, the
user's archival home directory will be used.
.Sp
Multiple files are combined with \fItar\fR\|(1) before copying to the
archival storage system if the \fB\-t\fR\ \fItarfile\fR option is
specified.  Files are tarred by first executing
.Sp
tar cf \- run10 run10.001, ..., run10.025 > \fItarfile\fR
.Sp
then \fItarfile\fR is transferred to the archival storage system.

.Ip "\fBarchive\ get\fR\ [getopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \ " 4

Copy files \fIfile1\fR [\fIfile2 ...\fR] in the archival storage
system to the current working directory.  Options \fIgetopts\fR
include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR, \fB\-C\fR\ \fIpath\fR, \fB\-s\fR,
\fB\-f\fR, \fB\-i\fR, \fB\-p\fR, \fB\-M\fR, \fB\-n\fR, \fB\-S\fR, \fB\-x\fR, and \fB\-z\fR.
If wildcards * and ? are used in specifying \fIfile1\fR [\fIfile2 ...\fR],
then double quotes must be used:
.Sp
archive\ get\ \*(L"\fIfile1\fR\ [\fIfile2\ ...\fR]\*(R"
.Sp
A source directory on the archival storage system may be specified
using the \fB\-C\fR\ \fIpath\fR option.  If \fB\-C\fR\ \fIpath\fR is not
specified, the user's archival home directory will be used.
.Sp
Archival storage files with a .tar, .tar.gz, or .tgz extension will
be extracted with the \fBgzip\fR and \fBtar\fR utilities if the \fB\-x\fR
option is present.  For example, if \fIfilea\fR is named run10.tgz,
then \fBarchive get \-x\fR will copy run10.tgz from the archival storage
system, then execute
.Sp
gunzip \fB\-f\fR < run10.tgz | tar xf -
.Sp
Specifying \fB\-x\fR has no effect on files with extensions different
from .tar, .tar.gz, or .tgz.

.Ip "\fBarchive\ mv\fR*\ [mvopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \fItarget\fR" 4

Move \fIfile1\fR [\fIfile2 ...\fR] to the target location \fItarget\fR;
\fIfile1\fR [\fIfile2 ...\fR] and \fItarget\fR are all located on the archival
storage system.
Options \fImvopts\fR include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR,
\fB\-C\fR\ \fIpath\fR, \fB\-s\fR, \fB\-f\fR, \fB\-i\fR, \fB\-M\fR, and \fB\-n\fR.
If \fItarget\fR is an existing directory, then \fIfile1\fR
[\fIfile2 ...\fR] are moved into \fItarget\fR.  If \fItarget\fR does not exist,
\fBarchive\ mv\fR will attempt to rename \fIfile1\fR as \fItarget\fR.  If
in this case [\fIfile2 ...\fR] is present or the names \fIfile1\fR and
\fItarget\fR are identical, \fBarchive mv\fR will fail and write an error
message to standard error.  If wildcards * and ? are used to specify
\fIfile1\fR [\fIfile2 ...\fR] and \fItarget\fR, then double quotes must be used:
.Sp
archive\ mv\ \*(L"\fIfile1\fR\ [\fIfile2\ ...\fR]\*(R"\ \*(L"\fItarget\fR\*(R"
.Sp
Note: do not include both \fIfile1\fR [\fIfile2 ...\fR] and \fItarget\fR in the
same set of quotes.  If wildcards are used to specify \fIfile1\fR
[\fIfile2 ...\fR] or \fItarget\fR, but not both, then quotes need only
delineate the argument containing wildcards.

.Ip "\fBarchive\ rm\fR*\ [rmopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \ \ \ \ \ \ " 4

Remove \fIfile1\fR [\fIfile2 ...\fR] on the archival storage system.
Options \fIrmopts\fR include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR, \fB\-C\fR\ \fIpath\fR,
\fB\-s\fR, \fB\-f\fR, \fB\-i\fR, \fB\-r\fR, and \fB\-n\fR.  If wildcards * and ? are used
to specify \fIfile1\fR [\fIfile2 ...\fR], then double quotes must be used:
.Sp
archive\ rm\ \*(L"\fIfile1\fR\ [\fIfile2\ ...\fR]\*(R"
.Sp
When \fB\-r\fR is specified, directories are emptied of files and removed.
The user is prompted for removal of any write-protected files, except
when the \fB\-f\fR option is used.

.Ip "\fBarchive\ ls\fR\ [lsopts]\ [\fIfile1\ ...\fR]\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ " 4

List [\fIfile1 ...\fR] on the archival storage system.  Options
\fIlsopts\fR include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR,
and other options identified by the manual page for \fBls\fR on the
archival storage system.  (See \fBman archive_ls(3)\fR for a full list of
\fIlsopts\fR.)  If wildcards * and ? are used to specify [\fIfile1 ...\fR],
then double quotes must be used:
.Sp
archive\ ls\ \*(L"[\fIfile1\ ...\fR]\*(R"
.Sp
If [\fIfile1 ...\fR] is not specified, then the contents of the user's home
directory on the archival storage system are listed.

.Ip "\fBarchive\ stat\fR\ [statopts]\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ " 4

Check and report status of archival storage system.
Options \fIstatopts\fR include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR, and \fB\-s\fR.
An exit status of 0 is returned when the system is operational; a
non-zero exit status is returned otherwise.  A message of the form
.Sp
hh:mm:ss mm/dd/yyyy \fIname\fR \fIstatus\fR [\fInote\fR]
.Sp
is printed to standard out, where hh:mm:ss\ mm/dd/yyyy is the current
date, \fIname\fR is the name of the archival storage system, \fIstatus\fR is
either \*(L"on-line\*(R" or \*(L"unavailable\*(R", and \fInote\fR is an optional text
message that may or may not be returned.

.Ip "\fBarchive\ mkdir\fR\ [mkdiropts]\ \fIdir1\fR\ [\fIdir2\ ...\fR]\ \ \ " 4

Create directories \fIdir1\fR [\fIdir2 ...\fR] on the archival storage
system.  Options \fImkdiropts\fR include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR,
\fB\-C\fR\ \fIpath\fR, \fB\-s\fR, \fB\-p\fR, \fB\-m\fR\ \fImode\fR, and \fB\-n\fR.

.Ip "\fBarchive\ rmdir\fR*\ [rmdiropts]\ \fIdir1\fR\ [\fIdir2\ ...\fR]\ \ \ \ \ " 4

Remove empty directories \fIdir1\fR [\fIdir2 ...\fR] from the archival
storage system.  Options \fIrmdiropts\fR include \fB\-retry N\fR,
\fB\-asf\fR\ \fIhost\fR, \fB\-C\fR\ \fIpath\fR, \fB\-s\fR, \fB\-p\fR, and \fB\-n\fR.  If
\fIdir1\fR [\fIdir2 ...\fR] are not empty, \fBarchive rmdir\fR will fail and
print an error message to standard error.  If wildcards * and ? are
used to specify \fIdir1\fR [\fIdir2 ...\fR], then double quotes must be used:
.Sp
archive\ rmdir\ \*(L"\fIdir1\fR\ [\fIdir2\ ...\fR]"

.Ip "\fBarchive\ chmod\fR*\ [chmodopts]\ \fImode\fR\ \fIfile1\fR\ [\fIfile2\ ...\fR]" 4

Change permissions for \fIfile1\fR [\fIfile2 ...\fR] according to \fImode\fR.
Options \fIchmodopts\fR include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR,
\fB\-C\fR \fIpath\fR, \fB\-s\fR, \fB\-R\fR, and \fB\-n\fR.  \fImode\fR may be either symbolic
or absolute.  See discussion of \fImode\fR syntax in the \fB\s-1OPTIONS\s0\fR section
 under \fB\-m\fR\ \fImode\fR.

.Ip "\fBarchive\ chgrp\fR*\ [chgrpopts]\ group\ \fIfile1\fR\ [\fIfile2\ ...\fR]" 4

Change the group \s-1ID\s0 of \fIfile1\fR [\fIfile2 ...\fR] to \fIgroup\fR, which
may be a decimal group \s-1ID\s0 or a group name found in the group file.
Options \fIchgrpopts\fR include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR, \fB\-C\fR \fIpath\fR,
\fB\-s\fR, \fB\-f\fR, \fB\-h\fR, \fB\-R\fR, and \fB\-n\fR.  Only an appropriately authorized
user may change the group of a file that is owned by another user.
Unless users are appropriately authorized, they must be a member of the
specified group to change the group of a file.  Unless the user is
appropriately authorized, \fBarchive chgrp\fR clears the set-user-\s-1ID\s0 and
set-group-\s-1ID\s0 file mode bits.

.Ip "\fBarchive\ chown\fR*\ [chownopts]\ owner[:group]\ \fIfile1\fR\ [\fIfile2\ ...\fR]" 4

Change the owner of \fIfile1\fR [\fIfile2 ...\fR] to \fIowner\fR;  The
optional \fIgroup\fR argument changes the group.  Options \fIchownopts\fR
include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR, \fB\-C\fR \fIpath\fR, \fB\-s\fR, \fB\-f\fR,
\fB\-h\fR, \fB\-R\fR, and \fB\-n\fR.  Only an appropriately authorized user may
change the owner of a file.  Unless the user is appropriately authorized,
\fBarchive chown\fR clears the set-user-\s-1ID\s0 and set-group-\s-1ID\s0 file mode
bits.

.Ip "\fBarchive\fR\ \fBmigrate\fR*\ [migrateopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ " 4


Control file migration of \fIfile1\fR [\fIfile2 ...\fR];  Options \fImigrateopts\fR
include \fB\-retry N\fR, \fB\-asf\fR\ \fIhost\fR, \fB\-C\fR \fIpath\fR, \fB\-s\fR, \fB\-n\fR, \fB\-M\fR,
\fB\-u\fR, and \fB\-q\fR.  Options \fB\-M\fR, \fB\-u\fR, and \fB\-q\fR specify the operation
performed by archive migrate, and only one may  be given in a command.
\fB\-M\fR migrates a remote file or set of files.  \fB\-u\fR
unmigrates a remote file or set of files, and \fB\-q\fR prints a message indicating
whether or not the \fIfile\fR\|(s) are migrated.  If none of these three options are
given, \fB\-M\fR is assumed.


.SH "OPTIONS"
By default, \fBarchive\fR assumes all arguments beginning with a dash (\-)
are command-line options.  Therefore, when \fBarchive\fR encounters an input
item of the form \-?, where ? does not match any of \fBarchive\fR's valid
options, \fBarchive\fR will print a message to standard error and return a
non-zero exit status.  Because this default behavior does not allow the
user to specify file or directory names that begin with a dash, you can
override this default behavior by including a dash-dash (--) in the
argument list.  When \fBarchive\fR encounters a dash-dash, it stops
parsing command options and assumes all following input items are
command arguments.
.PP
* archive currently does not support the options identified below with
asterisks (*).  There are two acceptions: \fB\-f\fR is assumed, but sufficient
error checking to enforce \fB\-f\fR for all possible errors is not currently
enabled.  Also, \fB\-m\fR\ \fImode\fR currently only handles asolute (as
opposed to sybmolic) mode specification.  Later versions of archive will
include all of the options and behavior listed below.
.Ip "\fB\-C\fR \fIpath\fR" 5
Manage files in the archival storage directory \fIpath\fR.  \fIpath\fR is
the user's archival storage home directory by default.
.Ip "\fB\-M\fR" 5
Once a file has been written or accessed on the archival storage
system, migrate the file to offline media.  Some centers do not support
this operation.  This option may prove useful for users with numerous
large data files to move, which, if moved all at once, would threaten
to fill the first tier of the archival storage system.  By specifying
\fB\-M\fR the user immediately makes room for subsequent archival data
transfers.
.Ip "\fB\-R\fR*" 5
Execute command recursively in all directories and subdirectories in
the argument list.  Same as \fB\-r\fR.  \fBarchive chmod\fR only takes \fB\-R\fR,
since \fB\-r\fR can have a different meaning for this command.
.Ip "\fB\-asf\fR \fIhost\fR" 5
Archival Storage Facility: execute command on the archival storage
facility \fIhost\fR.  This option overrides the default specified by
the \f(CW$ARCHIVE_HOST\fR environment variable.
.Ip "\fB\-D\fR" 5
Delete the local copy of source files involved in data transfer.  If
not set, all local source files are retained.  Note, \*(L"source files\*(R"
refers to files before they have been tarred with the \fB\-t\fR option or
local files that are not tarred before transfer.  \*(L"Source files\*(R" are
not the intermediate tarfiles generated when \fB\-t\fR is envoked.
Intermediate tarfiles generated with \fB\-t\fR are deleted by default
upon successful transfer.  To override this default behavior and
retain intermediate tarfiles, use \fB\-S\fR.
.Ip "\fB\-S\fR" 5
Save local copies of transferred tarfiles.
.Ip "\fB\-f\fR*" 5
Force creation, deletion, or modification of files/directories,
possibly overriding permissions set on existing files/directories
owned by the user.  When \fB\-f\fR is not present, the user is prompted
interactively to override permission settings on files owned by the
user.  Regardless the presence of \fB\-f\fR, \fBarchive\fR will not attempt
to change permissions on files or directories not owned by the user.
When used in conjunction with \fBarchive chgrp\fR or \fBarchive chown\fR,
the \fB\-f\fR option is identical to \fB\-s\fR.
.Ip "\fB\-h\fR*" 5
If the file is a symbolic link, change attributes of the symbolic
link.  If \fB\-h\fR is not used, attributes of the file referenced by
the symbolic link are changed.
.Ip "\fB\-i\fR*" 5
Force interactive confirmation by the user before overwriting or
removing an existing file or directory, both on the archival storage
system and local disks.  If \fB\-i\fR is not set and permission settings
permit, \fBarchive\fR will overwrite or remove existing files/directories.
.Ip "\fB\-m\fR \fImode\fR*" 5
Specify the permissions for the directory or file according to
\fImode\fR.  The syntax for \fImode\fR described here is also used by the
\fBarchive chmod\fR command.
.Sp
File \fImode\fRs may be either symbolic or absolute.  Absolute changes
to modes are specified with octal numbers, with \fImode\fR of the form
\fInnn\fR.  Here \fIn\fR is a number from 0 to 7.
.Sp
An absolute mode is given as an octal number constructed from the
\*(L"\s-1OR\s0\*(R" of the following modes:
.Ip "Code" 13
Description
.Ip "\ 400" 13
Sets read permission for owner.
.Ip "\ 200" 13
Sets write permission for owner.
.Ip "\ 100" 13
Sets execute (search in directory) permission for owner.
.Ip "\ 070" 13
Sets read, write, and execute (search in directory)
permission for group.
.Ip "\ 007" 13
Sets read, write, and execute (search in directory)
permission for others.
.Sp
Symbolic changes to modes are specified with mnemonic characters, with
\fImode\fR of the form
.Sp
[\fIwho\fR] \fIoperator\fR [\fIpermissions\fR]
.Sp
Note: if \fIwho\fR is specified, there should be no space between \fIwho\fR
and \fIoperator\fR; similarly, if \fIpermissions\fR is specified, there should
be no space between \fIoperator\fR and \fIpermissions\fR.
Here \fIwho\fR
is one or more characters that corresponds to user, group, other, or all
(\fBu\fR, \fBg\fR, \fBo\fR, or \fBa\fR); \fIoperator\fR is +, \-, or =,
signifying the addition, removal, or absolute assignment of permissions;
and \fIpermissions\fR is one or more characters that correspond to the type
of permission, e.g., read (\fBr\fR), write (\fBw\fR), execution (\fBx\fR)
for a given file.  For example, to add read and write permission for
group, \fImode\fR should be g+rw.
.Sp
Multiple symbolic modes separated by commas can be specified, although
no spaces may intervene between these modes.  Operations are performed
in the order given.  Multiple symbolic letters following a single
operator cause the corresponding operations to be performed
simultaneously.
.Sp
By default \fImode\fR is 777 (a+rwx) minus the bits set in the umask
on the archival storage system.
.Ip "\fB\-n\fR*" 5
Execute \fBarchive\fR in background mode and return zero exit status.
If \fB\-i\fR is set, \fB\-n\fR is ignored.
.Ip "\fB\-p\fR" 5
Create all non-existent parent directories in a specified archival
storage system path.  By default, if the parent directory of a target
pathname does not exist, \fBarchive\fR will fail and write an output error
message to standard error.
.Ip "\fB\-q\fR" 5
Query the migration status of a remote file.  Used with \fBarchive migrate\fR.
.Ip "\fB\-r\fR" 5
Execute command recursively in all directories and subdirectories in
the argument list.  Same as \fB\-R\fR.  \fBarchive chmod\fR only takes \fB\-R\fR,
since \fB\-r\fR has a different meaning for this command.
.Ip "\fB\-retry N\fR" 5
If \fBarchive\fR fails, retry \fBN\fR times, with increasing wait time
between repeated attempts.  Currently \fBarchive\fR sleeps for 5 seconds
plus two seconds for every iteration attempt.  Default is \fB\-retry 1000\fR.
.Ip "\fB\-s\fR" 5
Suppress printing of any output messages to standard error or
standard out, except for usage errors.
.Ip "\fB\-t\fR \fItarfile\fR" 5
This option handles archival storage files created with \fItar\fR\|(1).
See \fB\s-1DESCRIPTION\s0\fR section for \fBarchive put\fR above for discussion
of the \fB\-t\fR option.
.Ip "\fB\-u\fR" 5
Unmigrate a remote file.  Used with \fBarchive migrate\fR.
.Ip "\fB\-x\fR" 5
Extract (possibly gzipped) tarfiles after transfer from archival
storage with \fBarchive_get\fR.
.Ip "\fB\-z\fR" 5
Use \fIgzip\fR\|(1) to compress/uncompress files transfered to/from
archival storage.  The compressed file will have a .gz extension.
If \fB\-t\fR is also set, then the output from \fItar\fR\|(1) will be piped to
\fIgzip\fR\|(1), and the resulting compressed tar file will have a .tgz
extension.  See \fB\s-1EXAMPLES\s0\fR section below.
.SH "DIAGNOSTICS"
.SH "EXAMPLES"
To create directory dir1/dir2 on the data archive when dir1 doesn't exist:
.PP
.Vb 1
\&  archive mkdir -p dir1/dir2
.Ve
To get a listing of all files that end with .tex in directory d1 on the
data archive:
.PP
.Vb 1
\&  archive ls "d1/*.tex"
.Ve
To put local files f1 and f2 into a zipped tarfile files.tgz into directory
dir1 on the mass store and delete the local copies:
.PP
.Vb 1
\&  archive put -C dir1 -D -z -t files.tar f1 f2
.Ve
To tar a local directory localdir into and put the tar file (tarfile.tar) in
remote directory remotedir:
.PP
.Vb 1
\&  archive put -C remotedir -t tarfile.tar localdir
.Ve
To get and extract files from tarfile files.tar in mass-store directory dir1,
and save (not delete) the tarfile in the local directory:
.PP
.Vb 1
\&  archive get -C dir1 -x -S files.tar
.Ve
To get a file from directory dir1 and make sure that the remote file is
still/again migrated to slow storage:
.PP
.Vb 1
\&  archive get -C dir1 -M file
.Ve
.SH "ENVIRONMENT"
The following environment variables are checked by \fBarchive\fR:
\f(CW$ARCHIVE_HOST\fR, \f(CW$ARCHIVE_HOME\fR, and \f(CW$ARCHIVE_PROBE\fR.  If set,
\fBarchive\fR overrides default settings established during
installation.
.PP
Each environment variable is a comma-separated list (with no white
space), representing multiple archival storage facilities.  Currenlty
all \fBarchive\fR commands operate on only one system and use the first
element of each list, which is interpretted by \fBarchive\fR as the
default.  A different system may be specified with the \fB\-asf\fR option.
In the future, \fBarchive get\fR, \fBstat\fR, and \fBls\fR will be modified to
operate on multiple systems, sequencing through the entries in the
lists for these environment variables.
.Ip "\fB$\s-1ARCHIVE_HOST\s0\fR" 4
List of archival storage systems available at this site.
\fB\-asf\fR\ \fIhost\fR overrides this environment variable.
.Ip "\fB$\s-1ARCHIVE_HOME\s0\fR" 4
List of archival storage system home directories associated with
\f(CW$ARCHIVE_HOST\fR.  \f(CW$ARCHIVE_HOME\fR must contain either only one element,
which is used for all elements of \f(CW$ARCHIVE_HOME\fR, or a separate
element for each system specified by \f(CW$ARCHIVE_HOST\fR.
.Ip "\fB$\s-1ARCHIVE_PROBE\s0\fR" 4
List of flags ("yes\*(R" or \*(L"no") that indicate whether or not \fBarchive\fR
will attempt to check the existence, type, and size of files on the
archival storage system before and after transfer so that error
checking is possible.  A reason for setting \f(CW$ARCHIVE_PROBE\fR="no\*(R" could
be failure in accurate or complete reporting of file information by
the archival storage system.
.SH "FILES"
.SH "NOTES"
\fBarchive\fR is a command-line translation tool in the TUSC layer of the
Practical Supercomputing Toolkit (PST).  By using \fBarchive\fR (and other
elements of PST), users develop scripts and techniques that work,
without modification, at all institutions supported by PST.
.PP
Centers currently supported include ERDC, NAVO, ASC, AHPCRC.
.SH "SEE ALSO"
\fIarchive_put\fR\|(3),
.PP
\fIarchive_get\fR\|(3),
.PP
\fIarchive_mv\fR\|(3)*,
.PP
\fIarchive_rm\fR\|(3)*,
.PP
\fIarchive_ls\fR\|(3),
.PP
\fIarchive_stat\fR\|(3),
.PP
\fIarchive_mkdir\fR\|(3),
.PP
\fIarchive_rmdir\fR\|(3)*,
.PP
\fIarchive_chmod\fR\|(3)*,
.PP
\fIarchive_chgrp\fR\|(3)*,
.PP
\fIarchive_chown\fR\|(3)*.
.SH "AUTHOR"
Written and Copyright (C) 2001 by Joseph Werne, Michael Gourlay, and Chris
Bizon.  www.pstoolkit.org.
.SH "HISTORY"
Documentation v1.0 assembled Friday, July 13, 2001.
Revised (v1.1) Sep 18, 2001.

.rn }` ''
.IX Title "ARCHIVE 1"
.IX Name "B<archive> - perform basic file-handling operations on the local
archival storage system."

.IX Header "NAME"

.IX Header "SYNOPSIS"

.IX Header "DESCRIPTION"

.IX Header "COMMANDS"

.IX Item "\fBarchive\ put\fR\ [putopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]"

.IX Item "\fBarchive\ get\fR\ [getopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \ "

.IX Item "\fBarchive\ mv\fR*\ [mvopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \fItarget\fR"

.IX Item "\fBarchive\ rm\fR*\ [rmopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ \ \ \ \ \ \ "

.IX Item "\fBarchive\ ls\fR\ [lsopts]\ [\fIfile1\ ...\fR]\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "

.IX Item "\fBarchive\ stat\fR\ [statopts]\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "

.IX Item "\fBarchive\ mkdir\fR\ [mkdiropts]\ \fIdir1\fR\ [\fIdir2\ ...\fR]\ \ \ "

.IX Item "\fBarchive\ rmdir\fR*\ [rmdiropts]\ \fIdir1\fR\ [\fIdir2\ ...\fR]\ \ \ \ \ "

.IX Item "\fBarchive\ chmod\fR*\ [chmodopts]\ \fImode\fR\ \fIfile1\fR\ [\fIfile2\ ...\fR]"

.IX Item "\fBarchive\ chgrp\fR*\ [chgrpopts]\ group\ \fIfile1\fR\ [\fIfile2\ ...\fR]"

.IX Item "\fBarchive\ chown\fR*\ [chownopts]\ owner[:group]\ \fIfile1\fR\ [\fIfile2\ ...\fR]"

.IX Item "\fBarchive\fR\ \fBmigrate\fR*\ [migrateopts]\ \fIfile1\fR\ [\fIfile2\ ...\fR]\ "

.IX Header "OPTIONS"

.IX Item "\fB\-C\fR \fIpath\fR"

.IX Item "\fB\-M\fR"

.IX Item "\fB\-R\fR*"

.IX Item "\fB\-asf\fR \fIhost\fR"

.IX Item "\fB\-D\fR"

.IX Item "\fB\-S\fR"

.IX Item "\fB\-f\fR*"

.IX Item "\fB\-h\fR*"

.IX Item "\fB\-i\fR*"

.IX Item "\fB\-m\fR \fImode\fR*"

.IX Item "Code"

.IX Item "\ 400"

.IX Item "\ 200"

.IX Item "\ 100"

.IX Item "\ 070"

.IX Item "\ 007"

.IX Item "\fB\-n\fR*"

.IX Item "\fB\-p\fR"

.IX Item "\fB\-q\fR"

.IX Item "\fB\-r\fR"

.IX Item "\fB\-retry N\fR"

.IX Item "\fB\-s\fR"

.IX Item "\fB\-t\fR \fItarfile\fR"

.IX Item "\fB\-u\fR"

.IX Item "\fB\-x\fR"

.IX Item "\fB\-z\fR"

.IX Header "DIAGNOSTICS"

.IX Header "EXAMPLES"

.IX Header "ENVIRONMENT"

.IX Item "\fB$\s-1ARCHIVE_HOST\s0\fR"

.IX Item "\fB$\s-1ARCHIVE_HOME\s0\fR"

.IX Item "\fB$\s-1ARCHIVE_PROBE\s0\fR"

.IX Header "FILES"

.IX Header "NOTES"

.IX Header "SEE ALSO"

.IX Header "AUTHOR"

.IX Header "HISTORY"

