Document all commands

9 files changed, 530 insertions, 7 deletions

diff --git a/glacier b/glacier
index a05dfff..ccedf74 100755
--- a/glacier
+++ b/glacier
@@ -6,7 +6,6 @@ use Pod::Usage;
 use Pod::Man;
 use App::Glacier::Command;
 use File::Basename;
-
 
 my %comtab = (
     mkvault => sub {
@@ -61,6 +60,278 @@ sub getcom {
     return getcom($v[0]);
 }
 
+=head1 NAME
+
+glacier - command line utility for accessing Amazon Glacier storage
+
+=head1 SYNOPSIS
+
+B<glacier>
+[B<-?dn>]
+[B<-f> I<FILE>] 
+[B<--account=>I<STRING>]
+[B<--config-file=>I<FILE>]
+[B<--debug>]
+[B<--dry-run>]
+[B<--help>]    
+[B<--region=>I<STRING>]    
+[B<--usage>]
+I<COMMAND> [I<OPTIONS>] I<ARG>...
+
+=head1 DESCRIPTION
+
+Command line tool for accessing Amazon Glacier storage.  The I<COMMAND>
+instructs it what kind of manipulation is required.  Its action can be
+modified by I<OPTIONS> supplied after the command name.  Options occurring
+before it, affect the behavior of the program as a whole and are common
+for all commands.
+    
+The following is a short summary of existing commands.  For a detailed
+description about any of them, please run B<glacier I<COMMAND> --help>.    
+    
+=head2 glacier get I<VAULT> I<FILE> [I<LOCALNAME>]
+
+Download I<FILE> from the I<VAULT>.  The I<LOCALNAME> argument, if present,
+gives the name of the local file.
+    
+=head2 glacier ls [I<VAULT>] [I<FILES>...]
+
+Without arguments, lists all existing vaults.  With one argument, lists files
+in the specified vault.  If additional arguments are given, only files with 
+matching names will be listed.
+    
+=head2 glacier mkvault I<NAME>
+
+Creates a vault with given I<NAME>.    
+    
+=head2 glacier purge I<VAULT>
+
+Removes all archives from the vault.    
+    
+=head2 glacier put I<VAULT> I<FILE> [I<REMOTENAME>]
+
+Uploads I<FILE> to I<VAULT>.  The I<REMOTENAME>, if supplied, gives the
+new name for the uploaded copy of file.  If absent, the base name of I<FILE>
+is used.    
+    
+=head2 glacier rm I<VAULT> I<FILE>...
+
+Removes files from the vault.    
+    
+=head2 glacier rmvault I<NAME>
+
+Removes the vault.  It must be empty for the command to succeed.    
+    
+=head2 glacier sync I<VAULT>
+
+Synchronizes the local vault directory with its latest inventory.    
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-?>
+
+Displays short option summary.
+    
+=item B<--account=>I<STRING>
+
+Sets account ID to use.  See B<Multiple accounts>, below. 
+    
+=item B<-f>, B<--config-file=>I<FILE>
+
+Sets the name of the configuration file to use.  In the absense of this
+option, the environment variable B<GLACIER_CONF> is consulted.  If it
+is not set neither, the default file F</etc/glacier.conf> is read.  See
+the section B<CONFIGURATION> for its description.    
+    
+=item B<-d>, B<--debug>
+
+Increases debug output verbosity level.    
+    
+=item B<-n>, B<--dry-run>
+
+Dry run mode: do nothing, print everything.
+    
+=item B<--help>
+
+Display the detailed help page.
+    
+=item B<--region=>I<STRING>
+
+Sets the avaialbility region.    
+    
+=item B<--usage>
+
+Displays a succint command line usage summary,    
+
+=back    
+    
+=head1 CONFIGURATION
+
+Default configuration file is F</etc/glacier.conf>.  Its location is
+overridden by the value of the command line option B<--config-file> (B<-c>)
+and the environment variable B<GLACIER_CONF>.  The option takes precedence
+over the variable.
+
+Configuration file consists of statements in the form
+I<variable> B<=> I<value>), grouped into sections.  Whitespace is ignored,
+except that it serves to separate input tokens.  However, I<value> is read
+verbatim, including eventual whitespace characters that can appear within it.
+
+The following sections are recognized:
+
+=over 4
+
+=item B<[glacier]>
+
+Configures access to the Glacier service.  The following keywords are defined:
+    
+=over 8
+
+=item B<credentials => I<FILE>
+
+Sets the name of the credentials file.  See below for a detailed discussion.
+    
+=item B<access => I<KEYNAME>
+
+Defines Amazon access key or access ID for look up in the credentials file.
+    
+=item B<secret => I<SECRET>
+
+Sets the secret key.  The use of this statement is discouraged for
+security reason.    
+
+=item B<region => I<NAME>
+
+Sets the Amazon region.
+    
+=back
+
+The preferred way for storing credentials is in the I<credentials file>.  This
+file allows you to store all security sensitive data in a single place and to
+tighten permissions accordingly.  In the simplest case, this file contains a
+single line with your access and secret keys separated by a semicolon, e.g.:
+
+    AEBRGYTEBRET:RTFERYABNERTYR4HDDHEYRTWW
+
+Additionally, the default region can be specified after a second semicolon:
+
+    AEBRGYTEBRET:RTFERYABNERTYR4HDDHEYRTWW:us-west-1
+
+The default region is B<eu-west-1>.
+
+=item Multiple accounts
+    
+If you have several accounts, you can list their credentials on separate lines.
+In that case, B<glacier> will select the account with the access key supplied
+by the B<access> configuration statement, or the B<--account> command line
+option.  If neither of these are supplied, the first account in the file will
+be used.
+
+To further facilitate selection of the credential pair, each line can be tagged
+with the line B<#:I<NAME>> immediately preceding it.  In that case, the I<NAME>
+can be used to select it using the B<--account> option or B<access> configuration statement.
+
+Apart from these constructs, the credentials file can contain empty lines and
+comments (lines beginning with B<#> followed by any character, except B<:> ),
+which are ignored.
+
+=item B<[transfer]>
+
+Configures transfer values.  The section name can be optionally followed
+by B<upload> or B<download> to indicate that it applies only to transfers
+in that particular direction.    
+    
+=over 8
+
+=item B<single-part-size => I<SIZE>
+
+Defines the maximum size for single-part transfers.  Archives larger than
+I<SIZE> will be transferred using multiple-part procedure.  I<SIZE> must
+be a number, optionally followed by one of the following suffixes: B<K>,
+for kilobytes, B<M>, for megabytes, or B<G> for gigabytes.  Suffixes are
+case-insensitive.  The default is B<100M>.  
+    
+=item B<jobs => I<NUMBER>
+
+Sets the number of transfers running in parallel, if multi-part transfer is
+selected.  The default value is 16.    
+
+=item B<retries => I<NUMBER>
+
+Sets the number of retries for failed transfers.  Defaults to 10.    
+
+=back
+
+=item B<[database job]>
+
+Configures the I<job database>.  Job database is a local GDBM file, which
+B<glacier> uses to keep track of initiated Amazon Glacier jobs.
+    
+=over 8
+
+=item B<file => I<NAME>
+
+Defines the database file name.  The default is F</var/lib/glacier/job.db>.
+
+=item B<mode => I<OCTAL>
+
+Defines the file permissions.  It is used if the database does not exist and
+B<glacier> has to create it.  The default value is 644.
+    
+=back
+
+=item B<[database inv]>
+
+Configures B<inventory databases>.  Inventory databases associate file names
+with the corresponding Glacier archives and keep additional bookkeeping
+information.    
+    
+=over 8
+
+=item B<directory => I<DIR>
+
+Directory where to place the databases.  The default is F</var/lib/glacier/inv>.
+    
+=item B<mode => I<OCTAL>
+
+File mode for creating missing databases.  The default value is 644.
+
+=item B<ttl => I<NUMBER>
+
+Reserved for further use.    
+    
+=back    
+
+=back    
+    
+=cut
+    
+=head1 FILES
+
+=over 4
+
+=item F</etc/glacier.conf>
+
+Default configuration file.
+
+=item F</var/lib/glacier/job.db>
+
+Default job database name,
+
+=item F</var/lib/glacier/inv/I<VAULT>.db>
+
+Inventory database for the I<VAULT>.
+
+=back    
+    
+=head1 AUTHOR                                                                   
+                                                                                
+Sergey Poznyakoff <gray@gnu.org>
+    
+=cut
+
 my %args;
 
 GetOptions("hhh|?" => sub {
diff --git a/lib/App/Glacier/Command/CreateVault.pm b/lib/App/Glacier/Command/CreateVault.pm
index c53e47a..6d0b0f0 100644
--- a/lib/App/Glacier/Command/CreateVault.pm
+++ b/lib/App/Glacier/Command/CreateVault.pm
@@ -14,6 +14,14 @@ glacier mkvault - create a Glacier vault
 
 B<glacier mkvault> I<NAME>
 
+=head1 DESCRIPTION
+
+Creates a vault with the given I<NAME>
+
+=head1 SEE ALSO
+
+B<glacier>(1)    
+    
 =cut    
 
 sub run {
diff --git a/lib/App/Glacier/Command/DeleteFile.pm b/lib/App/Glacier/Command/DeleteFile.pm
index 47f2102..9ba8b40 100644
--- a/lib/App/Glacier/Command/DeleteFile.pm
+++ b/lib/App/Glacier/Command/DeleteFile.pm
@@ -17,6 +17,15 @@ B<glacier rm>
 I<VAULT>
 I<FILE>...    
 
+=head1 DESCRIPTION
+
+Removes listed files from the vault.  I<FILE> can contain version numbers,
+to select particular version of the file.  Globbing patterns are also allowed.
+
+=head1 SEE ALSO
+
+B<glacier>(1)    
+    
 =cut
 
 sub run {
diff --git a/lib/App/Glacier/Command/DeleteVault.pm b/lib/App/Glacier/Command/DeleteVault.pm
index 46f5e59..fbd4486 100644
--- a/lib/App/Glacier/Command/DeleteVault.pm
+++ b/lib/App/Glacier/Command/DeleteVault.pm
@@ -14,6 +14,14 @@ glacier rmvault - delete a Glacier vault
 
 B<glacier rmvault> I<NAME>
 
+=head1 DESCRIPTION
+
+Deletes the vault with the given I<NAME>
+
+=head1 SEE ALSO
+
+B<glacier>(1)    
+    
 =cut    
 
 sub run {
diff --git a/lib/App/Glacier/Command/Get.pm b/lib/App/Glacier/Command/Get.pm
index 92ccb56..5b62552 100644
--- a/lib/App/Glacier/Command/Get.pm
+++ b/lib/App/Glacier/Command/Get.pm
@@ -30,6 +30,51 @@ I<VAULT>
 I<FILE>
 [I<LOCALNAME>]
 
+=head1 DESCRIPTION
+
+Downloads I<FILE> from the I<VAULT>.  The local file name for the file is
+supplied by the I<LOCALNAME>.  If this argument is absent, the local name
+is formed from I<FILE> with the eventual version number part removed.
+
+=head1 OPTION
+
+=over 4
+    
+=item B<-f>, B<--force>
+
+Silently overwrites existing local file.
+    
+=item B<-i>, B<--interactive>
+
+If the local file already exists, asks for permission before overwriting
+it.    
+    
+=item B<-j>, B<--jobs=>I<N>
+
+Sets the number of concurrent download jobs for multiple-part downloads.
+The default is configured by the B<transfer.download.jobs> configuration
+statement.  If absent, the B<transfer.jobs> statement is used.  The
+default value is 16.    
+    
+=item B<--no-clobber>
+
+Never overwrite existing files.
+    
+=item B<-q>, B<--quiet>
+
+Don't display progress meter during multi-part downloads.
+    
+=item B<-t>, B<--test>
+
+Test mode.  Don't download the file, display only the status of the
+correspondig archive retrieval job.
+
+=back    
+    
+=head1 SEE ALSO
+
+B<glacier>(1).    
+    
 =cut
 
 use constant {
diff --git a/lib/App/Glacier/Command/ListVault.pm b/lib/App/Glacier/Command/ListVault.pm
index 10fa755..9950ff5 100644
--- a/lib/App/Glacier/Command/ListVault.pm
+++ b/lib/App/Glacier/Command/ListVault.pm
@@ -23,7 +23,116 @@ B<glacier list>
 [B<--time-style=>B<default>|B<full-iso>|B<long-iso>|B<iso>|B<locale>|B<+I<FORMAT>>]    
 [I<VAULT>]
 [I<FILE>...]    
- 
+
+=head1 DESCRIPTION
+
+Displays information about vaults and files.
+
+Used without arguments, displays the list of existing vaults.
+
+With one argument, lists files in the named vault, unless B<-d> is
+also specified, in which case, lists information about this vault only.
+
+With two or more arguments, lists files in I<VAULT> with names matching
+I<FILE> arguments.  The latter can contain version numbers and globbing
+patterns.
+
+=head1 OPTION
+
+=over 4
+    
+=item B<-S>
+    
+=item B<--sort=size>
+
+Sort by file size, largest first.
+    
+=item B<-U>
+
+=item B<--sort=none>
+
+Don't sort names.    
+    
+=item B<-d>, B<--directory>
+
+List just the names of vaults, rather than listing their contents.  This is
+the default if no arguments are supplied.    
+    
+=item B<-l>
+
+Print additional information.  For vaults: total size, number of archives
+in vault, creation date, and the vault name.  For files: file size, total
+number of stored versions, creation date, and the file name.
+    
+=item B<-t>
+
+=item B<--sort=time>
+
+Sort by modification time, newest first.
+        
+=item B<-h>, B<--human-readable>
+
+Append a size letter to each size (B<K>, B<M>, or B<G>).  Powers of 1024
+are used, so that B<M> stands for 1,048,576 bytes. 
+    
+=item B<--sort=>I<KEY>
+
+Sort output according to I<KEY>, which is one of: B<none>, B<name>, B<time>,
+B<size>.  Default is B<name>.
+    
+=item B<-r>, B<--reverse>
+
+Reverse the sort order.  E.g. with B<-t>, list youngest files first.    
+    
+=item B<--time-style=>I<STYLE>
+
+List timestamps in style STYLE.  The STYLE should be one of the
+following:
+
+=over 8
+
+=item B<+I<FORMAT>>
+
+List timestamps using I<FORMAT>, which is interpreted as the I<format>
+argument to B<strftime>(3) function.
+    
+=item B<default>
+
+Default format.  For timestamps not older than 6 month: month, day, hour
+and minute, e.g.: "May 23 15:00".  For older timestamps: month, day, and
+year, e.g.: "May 23  2017".
+    
+=item B<full-iso>
+
+List timestamps in full using ISO 8601 date, time, and time zone format with
+nanosecond precision, e.g., "2017-05-23 15:53:10.633308971 +0000".  This style
+is equivalent to "B<+%Y-%m-%d %H:%M:%S.%N %z>".
+
+=item B<long-iso>
+
+List ISO 8601 date and time in minutes, e.g., "2017-05-23 15:53".  Equivalent
+to "B<+%Y-%m-%d %H:%M>".    
+    
+=item B<iso>
+
+B<GNU ls>-compatible "iso": ISO 8601 dates for non-recent timestamps (e.g.,
+"2017-05-23"), and ISO 8601 month, day, hour, and minute for recent
+timestamps (e.g., "03-30 23:45").  Timestamp is considered "recent", if it
+is not older than 6 months ago.    
+
+=item B<locale>
+
+List timestamps in a locale-dependent form.  This is equivalent to B<+%c>.
+
+=back
+
+=back
+    
+=head1 SEE ALSO
+
+B<glacier>(1),    
+B<strftime>(3).
+
 =cut    
 
 sub getopt {
@@ -60,7 +169,7 @@ sub getopt {
     );
     $self->{_options}{sort} = 'name';
     my $rc = $self->SUPER::getopt(
-	'd' => \$self->{_options}{d},
+	'directory|d' => \$self->{_options}{d},
 	'l' => \$self->{_options}{l},
 	'sort=s' => \$self->{_options}{sort},
 	't' => sub { $self->{_options}{sort} = 'time' },
@@ -136,13 +245,13 @@ sub format_size {
 	    $suf = shift @suffixes;
 	}
     }
-    return sprintf("%*d%s", ($width || 10) - length($suf), int($size), $suf);
+    return sprintf("%*u%s", ($width || 10) - length($suf), int($size), $suf);
 }
 
 sub show_vault {
     my ($self, $vault) = @_;
     if ($self->{_options}{l}) {
-	printf("%8s % 8d %s %-24s\n",
+	printf("%8s % 8u %s %-24s\n",
 	       $self->format_size($vault->{SizeInBytes}),
 	       $vault->{NumberOfArchives},
 	       $vault->{CreationDate}->canned_format($self->{_options}{time_style}),
@@ -169,7 +278,7 @@ sub show_archive {
     my ($self, $arch) = @_;
 
     if ($self->{_options}{l}) {
-	printf("%8s % 8d %s %-24s\n",
+	printf("%8s % 8u %s %-24s\n",
 	       $self->format_size($arch->{Size}),
 	       $arch->{FileTotalVersions},
 	       $arch->{CreationDate}->canned_format($self->{_options}{time_style}),
diff --git a/lib/App/Glacier/Command/Purge.pm b/lib/App/Glacier/Command/Purge.pm
index 771a008..91f0b6c 100644
--- a/lib/App/Glacier/Command/Purge.pm
+++ b/lib/App/Glacier/Command/Purge.pm
@@ -16,8 +16,30 @@ B<glacier purge>
 [B<-fi>]
 [B<--force>]    
 [B<--interactive>]    
-B<VAULT>
+I<VAULT>
 
+=head1 DESCRIPTION
+
+Removes all archives from the vault.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-f>, B<--force>
+
+Remove all without asking.  This is the default.
+
+=item B<-i>, B<--interactive>
+
+Ask for confirmation before proceeding.
+
+=back
+    
+=head1 SEE ALSO
+
+B<glacier>(1).    
+    
 =cut
 
 sub getopt {
diff --git a/lib/App/Glacier/Command/Put.pm b/lib/App/Glacier/Command/Put.pm
index e670004..da5780b 100644
--- a/lib/App/Glacier/Command/Put.pm
+++ b/lib/App/Glacier/Command/Put.pm
@@ -25,6 +25,32 @@ I<VAULT>
 I<FILE>
 [I<REMOTENAME>]
 
+=head1 DESCRIPTION
+
+Uploads I<FILE> to I<VAULT>.  If I<REMOTENAME> is given, it supplies the new
+name for the file.
+
+=head1 OPTION
+
+=over 4
+
+=item B<-q>, B<--quiet>
+
+Don't display progress meter during multi-part uploads.
+
+=item B<-j>, B<--jobs=>I<N>
+
+Sets the number of concurrent jobs for multiple-part uploads.
+The default is configured by the B<transfer.upload.jobs> configuration
+statement.  If absent, the B<transfer.jobs> statement is used.  The
+default value is 16.    
+    
+=back    
+
+=head1 SEE ALSO
+
+B<glacier>(1).
+    
 =cut    
 
 sub getopt {
diff --git a/lib/App/Glacier/Command/Sync.pm b/lib/App/Glacier/Command/Sync.pm
index df797a9..90b7e39 100644
--- a/lib/App/Glacier/Command/Sync.pm
+++ b/lib/App/Glacier/Command/Sync.pm
@@ -21,6 +21,31 @@ B<glacier sync>
 [B<--force>]
 I<VAULT>
 
+=head1 DESCRIPTION
+
+Retrieves inventory for I<VAULT> and incorporates date into the local
+directory.  Use this command if the local directory went out of sync
+or was otherwise clobbered.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-d>, B<--delete>
+
+Deletes from the directory items that have no corresponding archive IDs in
+the inventory.
+    
+=item B<-f>, B<--force>
+
+Initiate new inventory retrieval job, even if one is already in progress.
+
+=back
+
+=head1 SEE ALSO
+
+B<glacier>(1).    
+    
 =cut
 
 sub getopt {