basic API documentation, not yet finished.

9 files changed, 484 insertions, 4 deletions

diff --git a/usr.sbin/pkg_add/Makefile b/usr.sbin/pkg_add/Makefile
index cd4fe8f8166..cd8ddce8ae8 100644
--- a/usr.sbin/pkg_add/Makefile
+++ b/usr.sbin/pkg_add/Makefile
@@ -1,6 +1,9 @@
-# $OpenBSD: Makefile,v 1.19 2005/02/15 09:13:05 espie Exp $
+# $OpenBSD: Makefile,v 1.20 2005/02/28 13:08:41 espie Exp $
+
+.include <bsd.own.mk>
 
 MAN=pkg_add.1 pkg_info.1 pkg_create.1 pkg_delete.1 pkg.1 pkg_mklocatedb.1
+POD2MAN=/usr/bin/pod2man
 
 PACKAGES= \
     OpenBSD/Add.pm \
@@ -39,10 +42,45 @@ SCRIPTS= \
 
 LIBBASE=/usr/libdata/perl5
 
+PODS= \
+    OpenBSD::IdCache \
+    OpenBSD::Mtree \
+    OpenBSD::PackingElement \
+    OpenBSD::PackingList \
+    OpenBSD::PkgCfl \
+    OpenBSD::PkgSpec \
+    OpenBSD::Ustar \
+    OpenBSD::Vstat
+
+.for p in ${PODS}
+.  ifndef NOMAN
+MANALL+= $p.cat3p
+MANSRCALL += $p.3p
+MANSRC_COOKIE=stamp-mansrc.build
+_quick3p+=${.CURDIR}/pod/$p.pod $p
+.    ifdef MANPS
+PSALL+= $p.ps3p
+.    endif
+.  else
+MANSRC_COOKIE=
+.  endif
+
+$p.3p: pod/$p.pod
+	${POD2MAN} --section=3p --official ${.ALLSRC} $@
+.endfor
+
+mansrc.build:
+.if !empty(_quick3p)
+	cd ${.OBJDIR} && ${POD2MAN} --section=3p --official ${_quick3p}
+.endif
+
 # Nothing to build
 depend:
-all:
+all: ${MANSRC_COOKIE}
 
+stamp-mansrc.build:
+	@cd ${.CURDIR} && exec ${MAKE} mansrc.build
+	@touch $@
 
 install: 
 .for i in ${PACKAGES}
@@ -58,8 +96,6 @@ install:
 
 clean:
 
-.include <bsd.own.mk>
-
 .if !defined(NOMAN)
 install: maninstall
 .include <bsd.man.mk>
@@ -67,3 +103,4 @@ install: maninstall
 
 .include <bsd.obj.mk>
 .include <bsd.subdir.mk>
+.PHONY: mansrc.build
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::IdCache.pod b/usr.sbin/pkg_add/pod/OpenBSD::IdCache.pod
new file mode 100644
index 00000000000..5a2727fc813
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::IdCache.pod
@@ -0,0 +1,27 @@
+$OpenBSD: OpenBSD::IdCache.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+
+=head1 NAME
+
+OpenBSD::IdCache - cache for uid and gid look-ups
+
+=head1 SYNOPSIS
+
+    use OpenBSD::IdCache;
+
+    my $ucache = new OpenBSD::UidCache;
+    my $uid = $ucache->lookup("espie");
+
+    my $gcache = new OpenBSD::GidCache;
+    my $gid = $gcache->lookup("wheel", 0);
+
+=head1 DESCRIPTION
+
+C<OpenBSD::IdCache> provides two classes: C<OpenBSD::UidCache>, for UIDs,
+and C<OpenBSD::GidCache> for GIDs.
+
+C<UidCache::new> creates a UID cache, which can be used to look up user
+names by using the C<lookup> method.  Looking up a numeric user name
+is a no-op. Non-existing IDs return a default value, which is normally
+C<undef> but can be provided as an extra argument to C<lookup>.
+
+C<GidCache::new> provides the same service for GIDs.
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Mtree.pod b/usr.sbin/pkg_add/pod/OpenBSD::Mtree.pod
new file mode 100644
index 00000000000..fcbda6ce6f9
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Mtree.pod
@@ -0,0 +1,27 @@
+$OpenBSD: OpenBSD::Mtree.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+
+=head1 NAME
+
+OpenBSD::Mtree - simple C<mtree(8)> spec parser
+
+=head1 SYNOPSIS
+    use OpenBSD::Mtree;
+
+    my %hier;
+
+    OpenBSD::Mtree::parse(\%hier, "/", "/etc/mtree/4.4BSD.dist");
+
+=head1 DESCRIPTION
+
+C<OpenBSD::Mtree> is a parser for C<mtree(8)> specifications that
+can reconstruct directory hierarchies. 
+
+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
+occur).
+
+C<OpenBSD::Mtree:parse(\%hash, $basedir, $filename)> is a convenience
+function which also handles opening the filehandle from C<$filename>
+and closing it after reading the specification.
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PackingElement.pod b/usr.sbin/pkg_add/pod/OpenBSD::PackingElement.pod
new file mode 100644
index 00000000000..0324821c721
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PackingElement.pod
@@ -0,0 +1,135 @@
+$OpenBSD: OpenBSD::PackingElement.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+
+=head1 NAME
+
+OpenBSD::PackingElement - C<pkg_add(1)> packing-elements object hierarchy
+
+=head1 SYNOPSIS
+
+    package OpenBSD::PackingElement;
+    sub method
+    {
+    }
+
+    package OpenBSD::PackingElement::Depend;
+    sub method
+    {
+    	my ($self, $args) = @_;
+	# do something
+    }
+
+    package main;
+    use OpenBSD::PackingList;
+
+    $plist = OpenBSD::PackingList->fromfile($filename);
+    $plist->visit('method', @args);
+
+=head1 DESCRIPTION
+
+C<OpenBSD::PackingElement> is the base class for all elements in a 
+packing-list (see L<OpenBSD::PackingList>).
+
+Manipulation of packing-lists mostly occurs through visitor patterns
+such as C<OpenBSD::PackingList::visit>: client code defines a method for
+each relevant class in the hierarchy and calls C<$plist-E<gt>visit('method')>
+to perform the processing.
+
+=over 4
+
+=item ::Meta
+
+base class for all meta information that can be reordered at will.
+
+=over 4
+
+=item ::Unique
+
+meta information with uniqueness properties.
+
+=over 4
+
+=item ::ExtraInfo
+
+=item ::Name
+
+=back
+
+=item ::Depend
+
+all dependency information.
+
+=over 4
+
+=item ::PkgDep
+
+deprecated
+
+=item ::NewDepend
+
+deprecated
+
+=item ::LibDepend
+
+deprecated
+
+=item ::Wantlib
+
+=item ::Dependency
+
+=back
+
+=item ::Conflict
+
+=over 4
+
+=item ::PkgConflict
+
+deprecated
+
+=item ::Conflict
+
+=back
+
+=back
+
+=item ::Annotation
+
+=item ::Object
+
+somewhat concrete elements in packing-lists.
+
+=over 4
+
+=item ::FileObject
+
+objects with a filename.
+
+=over 4
+
+=item ::FileBase
+
+abstract class for files.
+
+=item ::DirlikeObject
+
+abstract class for directories.
+
+=back
+
+=item ::Action
+
+stuff that performs some action during addition/removal of package.
+
+=item ::State
+
+annotation-like stuff that can't be easily moved around because it influences
+surrounding objects.
+
+=back
+
+=back
+
+=head1 CAVEATS
+
+Some aspects of this API are likely to change in the future, although the
+basic class hierarchy is now more or less worked out.
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod b/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod
new file mode 100644
index 00000000000..fd72cece141
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod
@@ -0,0 +1,9 @@
+$OpenBSD: OpenBSD::PackingList.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+
+=head1 NAME
+
+OpenBSD::PackingList - C<pkg_add(1)> packing-list manipulations
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod b/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod
new file mode 100644
index 00000000000..583b7dfd282
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PkgCfl.pod
@@ -0,0 +1,44 @@
+$OpenBSD: OpenBSD::PkgCfl.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+
+=head1 NAME
+
+OpenBSD::PkgCfl - C<pkg_create(1)> C<@conflict> handling
+
+=head1 SYNOPSIS
+
+    use OpenBSD::PkgCfl;
+
+    $clist = OpenBSD::PkgCfl->make_conflicts_list($plist);
+    @cfls = $clist->conflicts_with(@pkgnames);
+
+    OpenBSD::PkgCfl::register($plist, $state);
+    OpenBSD::PkgCfl::unregister($plist, $state);
+    @cfls = OpenBSD::PkgCfl::find_all($plist, $state);
+
+=head1 DESCRIPTION
+
+C<OpenBSD::PkgCfl> is the canonical interface to packing-list conflict
+handling.
+
+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 
+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 
+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, 
+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 
+information. The hash key C<conflict_list> is reserved for that purpose.
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PkgSpec.pod b/usr.sbin/pkg_add/pod/OpenBSD::PkgSpec.pod
new file mode 100644
index 00000000000..ad4e761938f
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PkgSpec.pod
@@ -0,0 +1,9 @@
+$OpenBSD: OpenBSD::PkgSpec.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+
+=head1 NAME
+
+OpenBSD::PkgSpec - C<packages-specs(7)> handling
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod b/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod
new file mode 100644
index 00000000000..2551ff5fd98
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod
@@ -0,0 +1,122 @@
+$OpenBSD: OpenBSD::Ustar.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+
+=head1 NAME
+
+OpenBSD::Ustar - simple access to Ustar C<tar(1)> archives
+
+=head1 SYNOPSIS
+
+    use OpenBSD::Ustar;
+    open(my $fh, "<", $filename);
+    $arc = OpenBSD::Ustar->new($fh, $destdir);
+    while (my $o = $arc->next()) {
+    	# decide whether we want to extract it, change object attributes
+	$o->create();
+    }
+
+
+=head1 DESCRIPTION
+
+C<OpenBSD::Ustar> provides an API to read archives created by C<tar(1)>.
+For the time being, it can only handle the USTAR archive format.
+
+Most client software will specialize C<OpenBSD::Ustar> to their own needs.
+Note however that C<OpenBSD::Ustar> is not designed for inheritance.
+Composition (putting a C<OpenBSD::Ustar> object inside your class) and
+forwarding methods (writing C<create> or C<next> methods that call the
+C<OpenBSD::Ustar> method) are the correct way to use this API.
+
+A filehandle C<$fh> is associated with an C<OpenBSD::Ustar> object through
+C<new>. 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.
+
+On the other hand, 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.
+
+Access to the archive object C<$arc> occurs through a loop that repeatedly 
+calls C<$o = $arc-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.
+
+Actual extraction is performed through C<$o-E<gt>extract()> and is not 
+mandatory. Thus, client code can control whether it wants to extract archive
+elements or not.
+
+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
+hold any resources and doesn't need any specific clean-up. However, client
+code is responsible for closing the filehandle and terminating any associated
+pipe process.
+
+An object C<$o> returned through C<next> holds all the characteristics of the 
+archive header:
+
+=over 20
+
+=item C<$o-E<gt>IsDir()>
+
+true if archive entry is a directory
+
+=item C<$o-E<gt>IsFile()>
+
+true if archive entry is a file
+
+=item C<$o-E<gt>IsLink()>
+
+true if archive entry is any kind of link
+
+=item C<$o-E<gt>IsSymLink()>
+
+true if archive entry is a symbolic link
+
+=item C<$o-E<gt>IsHardLink()>
+
+true if archive entry is a hard link
+
+=item C<$o-E<gt>{name}>
+
+filename
+
+=item C<$o-E<gt>{mode}>
+
+C<chmod(2)> mode
+
+=item C<$o-E<gt>{mtime}>
+
+C<utime(2)> modification time
+
+=item C<$o-E<gt>{uid}>
+
+owner user ID
+
+=item C<$o-E<gt>{gid}>
+
+owner group ID
+
+=item C<$o-E<gt>{uname}>
+
+owner user name
+
+=item C<$o-E<gt>{gname}>
+
+owner group name
+
+=item C<$o-E<gt>{linkname}>
+
+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()>, and will properly
+influence the resulting file.
+
+The relationship between C<uid> and C<uname>, and C<gid> and C<gname>
+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 C<$destdir> that was used
+for creating the C<$arc> C<OpenBSD::Ustar> object.
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod b/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod
new file mode 100644
index 00000000000..fff2929dc50
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod
@@ -0,0 +1,70 @@
+$OpenBSD: OpenBSD::Vstat.pod,v 1.1 2005/02/28 13:08:41 espie Exp $
+
+=head1 NAME
+
+OpenBSD::Vstat - virtual filesystem for C<pkg_add(1)> simulations
+
+=head1 SYNOPSIS
+
+    use OpenBSD::Vstat;
+
+    $h = OpenBSD::Vstat::add($filename, $size, $tag);
+    OpenBSD::Vstat::remove($filename, $size);
+    $e = OpenBSD::Vstat::vexists($filename);
+    OpenBSD::Vstat::tally();
+
+=head1 DESCRIPTION
+
+C<OpenBSD::Vstat> provides functions to layout a virtual file system on top
+of the real one.  This is generally used to simulate file system manipulations
+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 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
+using C<-e>.
+
+Both C<OpenBSD::Vstat::add> and C<OpenBSD::Vstat::remove> also know about
+Unix filesystem semantics, namely C<mount(8)> points and disk usage.
+They return a small object corresponding to the filename's file system with
+the following fields
+
+=over 8
+
+=item ro
+
+defined if the filesystem is read-only. Usually hard to add files there.
+
+=item nodev
+
+defined if the filesystem forbids devices.
+
+=item nosuid
+
+defined if the filesystem forbids SUID files.
+
+=item avail()
+
+returns the number of bytes still available on the filesystem.
+
+=back
+
+C<OpenBSD::Vstat::vexists> returns a true value if the filename exists.
+If it is a virtual name added through C<OpenBSD::Vstat::add>, it returns
+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.
+
+=head1 CAVEATS
+
+The API to this module may change.
+
+=head1 BUGS AND LIMITATIONS
+
+C<OpenBSD::Vstat> now handles C<chroot(8)> situations gracefully, but
+it doesn't know about symbolic links to directories and will report bogus
+results in complicated cases.