remove extra spaces, fix doc for Ustar (create, not extract), and document

callback.

11 files changed, 108 insertions, 104 deletions

diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Getopt.pod b/usr.sbin/pkg_add/pod/OpenBSD::Getopt.pod
index 26c6cefe63b..aaf73da3d9e 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::Getopt.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Getopt.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::Getopt.pod,v 1.2 2008/03/08 11:32:38 espie Exp $
+$OpenBSD: OpenBSD::Getopt.pod,v 1.3 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -8,7 +8,7 @@ OpenBSD::Getopt - Process single-characters switches
 
    use OpenBSD::Getopt;
 
-   our($opt_o, $opt_i, $opt_f, $opt_v); 
+   our($opt_o, $opt_i, $opt_f, $opt_v);
    getopts('oifv:',
     	{ 'v' => sub {
 		++$opt_v;}
@@ -16,7 +16,7 @@ OpenBSD::Getopt - Process single-characters switches
 
 =head1 DESCRIPTION
 
-This is similar to L<getopt(3)>. One call to C<getopts($optstring)> parses 
+This is similar to L<getopt(3)>. One call to C<getopts($optstring)> parses
 all the options using the C<$optstring> as a list of simple switches
 (letter) and switches with arguments (letter followed by C<:>).
 
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod b/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
index 7b8d3be47d7..2a9c12a5f1d 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::Intro.pod,v 1.11 2009/12/05 23:13:01 espie Exp $
+$OpenBSD: OpenBSD::Intro.pod,v 1.12 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -120,8 +120,8 @@ for performance and simplicity reasons.)
 
 =item update sets
 
-Each operation (installation, removal, or replacement of packages) 
-is cut up into small atomic operations, in order to guarantee maximal 
+Each operation (installation, removal, or replacement of packages)
+is cut up into small atomic operations, in order to guarantee maximal
 stability of the installed system. The package tools
 will try really hard to only deal with one or two packages at a time,
 in order to minimize combinatorial complexity, and to have a maximal number
@@ -136,7 +136,7 @@ under construction.  We have already met with update situations where
 dependencies between packages invert (A-1.0 depends on B-1.0, but B-0.0
 depends on A-0.0), or where files move between packages, which in
 theory will require update-sets with two new packages that replace two
-old packages.  We still cheat in a few cases, but in most cases, pkg_add
+old packages.  We still cheat in a few cases, but in most cases, L<pkg_add(1)>
 will recognize those situations, and merge updatesets as required.
 
 =item updater and tracker
@@ -144,13 +144,13 @@ will recognize those situations, and merge updatesets as required.
 Updatesets contain some initial information, such as a package name to
 install, or a package location to update.
 
-This information will be completed incrementally by a 
-C<OpenBSD::Update> updater object, which is responsible for figuring out 
+This information will be completed incrementally by a
+C<OpenBSD::Update> updater object, which is responsible for figuring out
 how to update each element of an updateset, if it is an older package, or
 to resolve a hint to a package name to a full package location.
 
 In order to avoid loops, a C<OpenBSD::Tracker> tracker
-object keeps track of all the package name statuses: what's queued for 
+object keeps track of all the package name statuses: what's queued for
 update, what is uptodate, or what can't be updated.
 
 =item dependency information
@@ -227,7 +227,7 @@ operations on all elements of a packing-list.
 
 =head2 PACKAGE ADDITION
 
-For package addition, L<pkg_add(1)> first checks that everything is correct, 
+For package addition, L<pkg_add(1)> first checks that everything is correct,
 then runs through the packing-list, and extracts element from the archive.
 
 =head2 PACKAGE DELETION
@@ -239,24 +239,24 @@ through all installed packages and removes stuff that's no longer used
 
 =head2 PACKAGE REPLACEMENT
 
-Package replacement is more complicated. It relies on package names 
-and conflict markers.  
+Package replacement is more complicated. It relies on package names
+and conflict markers.
 
-In normal usage, pkg_add installs only new stuff, and checks that all files 
-in the new package don't already exist in the file system.
+In normal usage, L<pkg_add(1)> installs only new stuff, and checks that all 
+files in the new package don't already exist in the file system.
 By convention, packages with the same stem are assumed to be different
 versions of the same package, e.g., screen-1.0 and screen-1.1 correspond
 to the same software, and users are not expected to be able to install
-both at the same time. 
+both at the same time.
 
-This is a conflict. 
+This is a conflict.
 
-One can also mark extra conflicts (if two software distributions install 
-the same file, generally a bad idea), or remove default conflict markers 
-(for instance, so that the user can install several versions of autoconf at 
+One can also mark extra conflicts (if two software distributions install
+the same file, generally a bad idea), or remove default conflict markers
+(for instance, so that the user can install several versions of autoconf at
 the same time).
 
-If pkg_add is invoked in replacement mode (-r), it will use conflict 
+If L<pkg_add(1)> is invoked in replacement mode (-r), it will use conflict
 information to figure out which package(s) it should replace. It will then
 operate in a specific mode, where it replaces old package(s) with a new one.
 
@@ -292,13 +292,13 @@ soon as a conflicts with b, or b conflicts with a.
 Package replacement is the basic operation behind package updates.
 In your average update, each individual package will be replaced
 by a more recent one, starting with dependencies, so that the installation
-stays functional the whole time.  Shared libraries enjoy a special status: 
-old shared libraries are kept around in a stub .lib-* package, so that 
+stays functional the whole time.  Shared libraries enjoy a special status:
+old shared libraries are kept around in a stub .lib-* package, so that
 software that depends on them keeps running. (Thus, it is vital that porters
 pay attention to shared library version numbers during an update.)
 
 An update operation starts with update sets that contain only old packages.
-There is some specific code (the C<OpenBSD::Update> module) which is used 
+There is some specific code (the C<OpenBSD::Update> module) which is used
 to figure out the new package name from the old one.
 
 In every update or replacement, pkg_add will first try to install or update
@@ -308,8 +308,8 @@ remove as they've become part of base OpenBSD.
 
 This search relies on stem names first (e.g., to update package
 foo-1.0, pkg_add -u will look for foo-* in the PKG_PATH), then it trims
-the search results by looking more closely inside the package candidates. 
-More specifically, their pkgpath (the directory in the ports tree from which 
+the search results by looking more closely inside the package candidates.
+More specifically, their pkgpath (the directory in the ports tree from which
 they were compiled). Thus, a package
 that comes from category/someport/snapshot will never replace a package
 that comes from category/someport/stable. Likewise for flavors.
@@ -317,8 +317,8 @@ that comes from category/someport/stable. Likewise for flavors.
 Finally, pkg_add -u decides whether the update is needed by comparing
 the package version and the package signatures: a package will not be
 downgraded to an older version. A package signature is composed of
-the name of a package, together with relevant dependency information: 
-all wantlib versions, and all run dependencies versions. 
+the name of a package, together with relevant dependency information:
+all wantlib versions, and all run dependencies versions.
 pkg_add only replaces packages with different signatures.
 
 Currently, pkg_add -u stops at the first entry in the PKG_PATH from which
@@ -336,7 +336,7 @@ some complicated update scenarios are not fully handled through updatesets.
 
 =item *
 
-Version number handling does not yet extends to package signatures. 
+Version number handling does not yet extends to package signatures.
 Thus, some spurious downgrades may happen if the packagename itself does not
 change.
 
@@ -474,7 +474,7 @@ shared library specificities when handled as dependencies.
 
 =item OpenBSD::Subst
 
-conventions used for substituting variables during L<pkg_create(1)>, 
+conventions used for substituting variables during L<pkg_create(1)>,
 and related algorithms.
 
 =item OpenBSD::Temp
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Mtree.pod b/usr.sbin/pkg_add/pod/OpenBSD::Mtree.pod
index 766b0ce2a44..1fdc6bd8764 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::Mtree.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Mtree.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::Mtree.pod,v 1.2 2005/03/07 21:39:53 espie Exp $
+$OpenBSD: OpenBSD::Mtree.pod,v 1.3 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -15,9 +15,9 @@ OpenBSD::Mtree - simple C<mtree(8)> spec parser
 =head1 DESCRIPTION
 
 C<OpenBSD::Mtree> is a parser for C<mtree(8)> specifications that
-can reconstruct directory hierarchies. 
+can reconstruct directory hierarchies.
 
-The basic function C<OpenBSD::Mtree::parse_fh(\%hash, $basedir, $fh)> 
+The basic function C<OpenBSD::Mtree::parse_fh(\%hash, $basedir, $fh)>
 will populate the hash C<$hash> with defined entries for each directory
 seen while reading from C<$fh>, assuming the specification is to be interpreted
 relative to C<$basedir> (some canonicalization of directory names will
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PackageName.pod b/usr.sbin/pkg_add/pod/OpenBSD::PackageName.pod
index d2abfba6657..7190feeabe7 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::PackageName.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PackageName.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::PackageName.pod,v 1.2 2006/02/22 18:34:49 bernd Exp $
+$OpenBSD: OpenBSD::PackageName.pod,v 1.3 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -13,7 +13,7 @@ OpenBSD::PackageName - package names handling
    ($stem, $version, @flavors) = OpenBSD::PackageName::splitname($pkgname);
    $stem = OpenBSD::PackageName::splitstem($pkgname);
 
-   OpenBSD::PackageName::is_stem($stem) == 1 
+   OpenBSD::PackageName::is_stem($stem) == 1;
    OpenBSD::PackageName::is_stem($pkgname) == 0;
 
    @candidates = OpenBSD::PackageName::findstem($stem, @pkgnames);
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PackingElement.pod b/usr.sbin/pkg_add/pod/OpenBSD::PackingElement.pod
index 5ae7be6921f..c8153f5b2ec 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::PackingElement.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PackingElement.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::PackingElement.pod,v 1.8 2008/10/28 18:10:04 espie Exp $
+$OpenBSD: OpenBSD::PackingElement.pod,v 1.9 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -26,7 +26,7 @@ OpenBSD::PackingElement - C<pkg_add(1)> packing-elements object hierarchy
 
 =head1 DESCRIPTION
 
-C<OpenBSD::PackingElement> is the base class for all elements in a 
+C<OpenBSD::PackingElement> is the base class for all elements in a
 packing-list (see L<OpenBSD::PackingList(3p)> and C<pkg_create(1)>).
 
 Manipulation of packing-lists mostly occurs through visitor patterns
@@ -247,7 +247,7 @@ C<::Extra>, C<::Sample> and C<::Sampledir>
 abstract class corresponding to files and directories.
 Default constructor depends on a C<dirclass> property, that may
 create objects from another class if their name ends with a C</>.
-The full object name is normally computed relative to the current 
+The full object name is normally computed relative to the current
 working directory as set in C<::State>.
 
 =over 4
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod b/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod
index e3223d7bb80..956b809e47a 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::PackingList.pod,v 1.7 2007/05/02 15:17:36 espie Exp $
+$OpenBSD: OpenBSD::PackingList.pod,v 1.8 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -57,7 +57,7 @@ Packing-lists can be obtained using the following methods: from an
 opened file handle using C<OpenBSD::PackingList-E<gt>read($fh)>, from
 an existing file using C<OpenBSD::PackingList-E<gt>fromfile($filename)>,
 from a scalar in memory using C<OpenBSD::PackingList-E<gt>fromfile(\$scalar)>,
-or from an installed package using 
+or from an installed package using
 C<OpenBSD::PackingList-E<gt>from_installation($pkgname)>.
 
 Since building a full packing-list is a complex operation and can consume
@@ -68,7 +68,7 @@ obtain partial packing-lists with only some information:
 
 =item SharedItemsOnly
 
-read only stuff that may be shared between packages, e.g., new users, 
+read only stuff that may be shared between packages, e.g., new users,
 groups and directories.
 
 =item LibraryOnly
@@ -93,15 +93,15 @@ read only what is needed to decide to update a package.
 
 =back
 
-A complete packing-list C<$plist> may be written to disk using the 
+A complete packing-list C<$plist> may be written to disk using the
 following methods:
 C<$plist-E<gt>write($fh)> will write a packing-list to an
 opened file handle C<$fh>, C<$plist-E<gt>tofile($filename)> will
-write a packing-list to a file named C<$filename>, and 
+write a packing-list to a file named C<$filename>, and
 C<$plist-E<gt>to_installation()> will write a packing-list during
 registration of a package.
 
-In addition C<$plist-E<gt>to_cache()> will register enough 
+In addition C<$plist-E<gt>to_cache()> will register enough
 information from a package to let the framework believe the package has
 been installed. This is used for the simulation modes of C<pkg_add(1)>
 and friends.
@@ -112,9 +112,9 @@ in the same order.  It is a good way to validate packing-lists and normalize
 them, though.
 
 Building packing-lists entails cooperation with C<OpenBSD::PackingElement>.
-Packing-lists are usually built by adding objects from an 
+Packing-lists are usually built by adding objects from an
 C<OpenBSD::PackingElement> subclass to the packing-list, either with
-the C<add> constructor:  
+the C<add> constructor:
 C<OpenBSD::PackingElement::SUBCLASS-E<gt>add($plist, $args)>, which builds
 a packing element and adds it to the packing-list in one operation, or with
 the C<add_object> method, which takes an existing packing element and adds it
@@ -129,5 +129,5 @@ of the package name and dependency information.
 C<$plist-E<gt>visit($method, @args)> is a visitor pattern, calling
 C<method(@args)> on each element of the packing-list in a specific order.
 
-As a feature, if C<OpenBSD::PackingElement-E<gt>can(method)>, 
+As a feature, if C<OpenBSD::PackingElement-E<gt>can(method)>,
 C<$plist-E<gt>method(@args)> will be turned into a visitor call automatically.
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod b/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod
index 583b7dfd282..de3d92be219 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::PkgCfl.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+$OpenBSD: OpenBSD::PkgCfl.pod,v 1.2 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -20,25 +20,25 @@ OpenBSD::PkgCfl - C<pkg_create(1)> C<@conflict> handling
 C<OpenBSD::PkgCfl> is the canonical interface to packing-list conflict
 handling.
 
-Conflict information can be extracted from a packing-list 
+Conflict information can be extracted from a packing-list
 (see L<OpenBSD::PackingList>) through the
 C<OpenBSD::PkgCfl> class method. The result is an opaque object C<$clist> that
-can be queried to find out which package names conflict with the 
+can be queried to find out which package names conflict with the
 packing-list.   A query of the form C<$clist-E<gt>conflicts_with(@pkgnames)>
 will extract from the list the package names that actually conflict with
 the packing-list.
 
 Most handling of conflict information happens through the higher level
-interface: C<OpenBSD::PkgCfl::register>, C<OpenBSD::PkgCfl::unregister> 
-and C<OpenBSD::PkgCfl::find_all>.  Package tools usually handle installed 
+interface: C<OpenBSD::PkgCfl::register>, C<OpenBSD::PkgCfl::unregister>
+and C<OpenBSD::PkgCfl::find_all>.  Package tools usually handle installed
 packages, and this interface automatically takes the initial set of installed
-packages into account. The C<register> and C<unregister> functions must 
-be used to add and remove a packing-list from the set of installed packages, 
+packages into account. The C<register> and C<unregister> functions must
+be used to add and remove a packing-list from the set of installed packages,
 where conflict information is concerned.
 
 The C<find_all> function can be used to find out about all possible conflicts
 a new packing-list will entail, before actually adding the package.
 
-The extra argument C<$state> is a hash used to record system-wide options. 
-In this case, it acts as a hidden object that records all conflict 
+The extra argument C<$state> is a hash used to record system-wide options.
+In this case, it acts as a hidden object that records all conflict
 information. The hash key C<conflict_list> is reserved for that purpose.
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::RequiredBy.pod b/usr.sbin/pkg_add/pod/OpenBSD::RequiredBy.pod
index 4927bd26daa..88a7fc8df48 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::RequiredBy.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::RequiredBy.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::RequiredBy.pod,v 1.3 2007/06/01 22:35:47 espie Exp $
+$OpenBSD: OpenBSD::RequiredBy.pod,v 1.4 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -42,9 +42,9 @@ for installed packages.
 If C<$main::not> is true, all change operations are done internally and
 never written to disk.
 
-C<$o = OpenBSD::RequiredBy-E<gt>new($pkgname)> gives access to the reverse 
+C<$o = OpenBSD::RequiredBy-E<gt>new($pkgname)> gives access to the reverse
 dependencies,
-C<$o =OpenBSD::Requiring-E<gt>new($pkgname)>  gives access to the forward 
+C<$o =OpenBSD::Requiring-E<gt>new($pkgname)>  gives access to the forward
 dependencies.
 
 Such an object can be used to list the dependencies C<$o-E<gt>list>,
@@ -52,7 +52,7 @@ add names to them C<$o-E<gt>add(name1, name2, ...)> or remove name from
 them C<$o-E<gt>delete(name1, name2, ...)>.
 
 The full list of forward dependencies (transitive closure) from a set of
-packages is given by 
+packages is given by
 C<OpenBSD::RequiredBy-E<gt>compute_closure($name1, name2, ...)>.
 Likewise,
 C<OpenBSD::Requiring-E<gt>compute_closure($name1, name2, ...)>
@@ -61,7 +61,7 @@ yields the list of reverse dependencies.
 Those lists of dependencies trim duplicates and, unless C<$main::not> is true,
 disk files are automatically synchronized whenever the lists change.
 
-C<OpenBSD::RequiredBy> maintains a cache for efficiency. When an 
-installed package is deleted completely, 
-C<OpenBSD::RequiredBy-E<gt>forget($dir)> and 
+C<OpenBSD::RequiredBy> maintains a cache for efficiency. When an
+installed package is deleted completely,
+C<OpenBSD::RequiredBy-E<gt>forget($dir)> and
 C<OpenBSD::Requiring-E<gt>forget($dir)> will remove the cache entries.
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Search.pod b/usr.sbin/pkg_add/pod/OpenBSD::Search.pod
index ae2bb40db65..5e2197d0291 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::Search.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Search.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::Search.pod,v 1.2 2009/11/10 11:01:15 espie Exp $
+$OpenBSD: OpenBSD::Search.pod,v 1.3 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -6,7 +6,7 @@ OpenBSD::Search - package names matching framework
 
 =head1 SYNOPSIS
 
-   use OpenBSD::Search; 
+   use OpenBSD::Search;
 
    # pkgspec objects
    my $search_object = OpenBSD::Search::PkgSpec->new($pattern);
@@ -23,13 +23,13 @@ OpenBSD::Search - package names matching framework
 
 =head1 DESCRIPTION
 
-C<OpenBSD::Search> provides a search infrastructure 
+C<OpenBSD::Search> provides a search infrastructure
 for C<OpenBSD::PackageRepository> objects.
 
 A given repository can be searched for existing packages using
 C<$repo-E<gt>match_locations($search1, $filter1, ...);>
 
-It returns a reference to a list of matching C<OpenBSD::PackageLocation> 
+It returns a reference to a list of matching C<OpenBSD::PackageLocation>
 objects.
 
 A repository list can be searched in a similar way: the search
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod b/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod
index f53bf62371b..52447a1e050 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::Ustar.pod,v 1.12 2008/06/02 23:31:33 jmc Exp $
+$OpenBSD: OpenBSD::Ustar.pod,v 1.13 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -11,11 +11,11 @@ OpenBSD::Ustar - simple access to Ustar C<tar(1)> archives
 
     open(my $in, "<", $arcnameforreading) or die;
     $rdarc = OpenBSD::Ustar->new($in, $destdir);
-    while (my $o = $rdarc->next()) {
+    while (my $o = $rdarc->next) {
     	# decide whether we want to extract it, change object attributes
-	$o->create();
+	$o->create;
     }
-    $rdarc->close();
+    $rdarc->close;
 
     # for writing
     open(my $out, ">", $arcnameforwriting) or die;
@@ -23,40 +23,40 @@ OpenBSD::Ustar - simple access to Ustar C<tar(1)> archives
     # loop
     	my $o = $wrarc->prepare($filename);
 	# tweak some entry parameters
-	$o->write();
+	$o->write;
 
-    $wrarc->close();
+    $wrarc->close;
 
-    # for copying 
+    # for copying
     open(my $in, "<", $arcnameforreading) or die;
     $rdarc = OpenBSD::Ustar->new($in, $destdir);
     open(my $out, ">", $arcnameforwriting) or die;
     $wrarc = OpenBSD::Ustar->new($fh, $destdir);
-    while (my $o = $rdarc->next()) {
+    while (my $o = $rdarc->next) {
     	$o->copy($wrarc);
     }
-    $rdarc->close();
-    $wrarc->close();
+    $rdarc->close;
+    $wrarc->close;
 
 =head1 DESCRIPTION
 
-C<OpenBSD::Ustar> provides an API to read, write and copy archives compatible 
+C<OpenBSD::Ustar> provides an API to read, write and copy archives compatible
 with C<tar(1)>.
 For the time being, it can only handle the USTAR archive format.
 
 A filehandle C<$fh> is associated with an C<OpenBSD::Ustar> object through
-C<new>. For archive reading, the filehandle should support 
-C<read>. C<OpenBSD::Ustar> does not rely on C<seek> or C<rewind> in order 
-to be usable on pipe outputs. For archive writing, the filehandle should 
+C<new>. For archive reading, the filehandle should support
+C<read>. C<OpenBSD::Ustar> does not rely on C<seek> or C<rewind> in order
+to be usable on pipe outputs. For archive writing, the filehandle should
 support C<print>.
 
 Note that read and write support are mutually exclusive, though there is
 no need to specify the mode used at creation time; it is implicitly
 provided by the underlying filehandle.
 
-Read access to an archive object C<$rdarc> occurs through a loop that 
-repeatedly calls C<$o = $rdarc-E<gt>next()> to obtain the next archive entry.  
-It returns an archive entry object C<$o> that can be 
+Read access to an archive object C<$rdarc> occurs through a loop that
+repeatedly calls C<$o = $rdarc-E<gt>next> to obtain the next archive entry.
+It returns an archive entry object C<$o> that can be
 queried to decide whether to extract this entry or not.
 
 Write access to an archive object C<$wrarc> occurs through a user-directed
@@ -73,54 +73,58 @@ Note that C<OpenBSD::Ustar> does not do any caching. The client
 code is responsible for retrieving and storing archives if it
 needs to scan through them multiple times in a row.
 
-Actual extraction is performed through C<$o-E<gt>extract()> and is not 
+Actual extraction is performed through C<$o-E<gt>create> and is not
 mandatory. Thus, client code can control whether it wants to extract archive
 elements or not.
 
-Small files can also be directly extracted to a scalar using 
-C<$v = $o-E<gt>contents()>.
+The C<create> method can take an optional C<$callback> argument, which will
+be called regularly while extracting large objects, as C<&$callback($donesize)>,
+with C<$donesize> the number of bytes already extracted.
 
-Actual writing is performed through C<$o-E<gt>write()> and is not mandatory
+Small files can also be directly extracted to a scalar using
+C<$v = $o-E<gt>contents>.
+
+Actual writing is performed through C<$o-E<gt>write> and is not mandatory
 either.
 
-Archives should be closed using C<$wrarc-E<gt>close()>, which will
+Archives should be closed using C<$wrarc-E<gt>close>, which will
 pad the archive as needed and close the underlying file handle.
 In particular, this is mandatory for write access, since valid archives
 require blank-filled blocks.
 
-This is equivalent to calling C<$wrarc-E<gt>pad()>, which will
+This is equivalent to calling C<$wrarc-E<gt>pad>, which will
 complete the archive with blank-filled blocks, then closing the
 associated file handle manually.
 
 Client code may decide to abort archive extraction early, or to run it through
-until C<$arc-E<gt>next()> returns false.  The C<OpenBSD::Ustar> object doesn't
+until C<$arc-E<gt>next> returns false.  The C<OpenBSD::Ustar> object doesn't
 hold any hidden resources and doesn't need any specific clean-up.
 
-Client code is only responsible for closing the underlying filehandle and 
+Client code is only responsible for closing the underlying filehandle and
 terminating any associated pipe process.
 
-An object C<$o> returned through C<next> or through C<prepare> holds all 
+An object C<$o> returned through C<next> or through C<prepare> holds all
 the characteristics of the archive header:
 
 =over 20
 
-=item C<$o-E<gt>IsDir()>
+=item C<$o-E<gt>IsDir>
 
 true if archive entry is a directory
 
-=item C<$o-E<gt>IsFile()>
+=item C<$o-E<gt>IsFile>
 
 true if archive entry is a file
 
-=item C<$o-E<gt>IsLink()>
+=item C<$o-E<gt>IsLink>
 
 true if archive entry is any kind of link
 
-=item C<$o-E<gt>IsSymLink()>
+=item C<$o-E<gt>IsSymLink>
 
 true if archive entry is a symbolic link
 
-=item C<$o-E<gt>IsHardLink()>
+=item C<$o-E<gt>IsHardLink>
 
 true if archive entry is a hard link
 
@@ -159,7 +163,7 @@ name of the source link, if applicable
 =back
 
 The fields C<name>, C<mode>, C<mtime>, C<uid>, C<gid> and C<linkname>
-can be altered before calling C<$o-E<gt>create()> or C<$o-E<gt>write()>, 
+can be altered before calling C<$o-E<gt>create> or C<$o-E<gt>write>,
 and will properly influence the resulting file.
 
 The relationship between C<uid> and C<uname>, and C<gid> and C<gname>
@@ -168,7 +172,7 @@ conforms to the USTAR format usual behavior.
 In addition, client code may define C<$o-E<gt>{cwd}> in a way similar
 to C<tar(1)>'s C<-C> option to affect the creation of hard links.
 
-All creation commands happen relative to the current destdir of 
+All creation commands happen relative to the current destdir of
 the C<$arc> C<OpenBSD::Ustar> object.  This is set at creation, and can
 later be changed through C<$arc-E<gt>destdir($value)>.
 
@@ -182,5 +186,5 @@ the destination archive C<$arc> into believing C<$o> has been copied under the
 given C<$name>, so that further hard links will be copied over.
 
 Archives can be copied by creating separate archives for reading and writing.
-Calling C<$o = $rdarc-E<gt>next()> and C<$o-E<gt>copy($wrarc)> will copy
+Calling C<$o = $rdarc-E<gt>next> and C<$o-E<gt>copy($wrarc)> will copy
 an entry obtained from C<$rdarc> to C<$wrarc>.
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod b/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod
index d3181901796..60e9e9d5dd4 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::Vstat.pod,v 1.3 2007/04/17 00:00:55 espie Exp $
+$OpenBSD: OpenBSD::Vstat.pod,v 1.4 2009/12/17 11:41:30 espie Exp $
 
 =head1 NAME
 
@@ -21,7 +21,7 @@ before doing them for real.
 
 The functions C<OpenBSD::Vstat::add> (respectively
 C<OpenBSD::Vstat::remove>) can be used to add a filename to
-the file system (resp. remove a filename from the file system).  
+the file system (resp. remove a filename from the file system).
 The function C<OpenBSD::Vstat:vexists> looks for
 a given filename: first it checks if it has been added or removed in
 the virtual filesystem. Failing that, it looks into the real file system
@@ -63,7 +63,7 @@ the C<$tag> specified as an optional argument. Otherwise, it returns 1.
 C<OpenBSD::Vstat:tally> displays a summary of filesystem manipulations
 after a series of additions and removals.
 
-Due to the way packages get updated, size modifications through 
+Due to the way packages get updated, size modifications through
 C<OpenBSD::Vstat::remove> are delayed until the next call to
 C<OpenBSD::Vstat::synchronize>: old files must be removed before
 adding the new files in order to properly account for collisions,