Documentation additions and fixes

Added documentation for the new object and acl list searches to
perl/Wallet/Admin.pm and server/wallet-admin.  Also fixed a POD error
in perl/Wallet/Kadmin.pm's docs.

3 files changed, 78 insertions, 13 deletions

diff --git a/perl/Wallet/Admin.pm b/perl/Wallet/Admin.pm
index 701c813..c86cbba 100644
--- a/perl/Wallet/Admin.pm
+++ b/perl/Wallet/Admin.pm
@@ -475,12 +475,14 @@ initialize() uses C<localhost> as the hostname and PRINCIPAL as the user
 when logging the history of the ADMIN ACL creation and for any subsequent
 actions on the object it returns.
 
-=item list_acls()
+=item list_acls(TYPE, SEARCH)
 
-Returns a list of all ACLs in the database.  The return value is a list of
-references to pairs of ACL ID and name.  For example, if there are two
-ACLs in the database, one with name "ADMIN" and ID 1 and one with name
-"group/admins" and ID 3, list_acls() would return:
+Returns a list of all ACLs matching a search type and string in the 
+database, or all ACLs if no search information is given.  The return value 
+is a list of references to pairs of ACL ID and name.  For example, if 
+there are two ACLs in the database, one with name "ADMIN" and ID 1 and one 
+with name "group/admins" and ID 3, list_acls() with no arguments would 
+return:
 
     ([ 1, 'ADMIN' ], [ 3, 'group/admins' ])
 
@@ -489,12 +491,20 @@ at least one ACL, but an error can be distinguished from the odd case of a
 database with no ACLs by calling error().  error() is guaranteed to return
 the error message if there was an error and undef if there was no error.
 
-=item list_objects()
+There are currently two search types.  'empty' takes no arguments, and will
+return only those acls that have no entries within them.  'entry' takes two 
+arguments -- an entry scheme and an entry identifier -- and will return 
+any ACLs with an entry that matches the given scheme and contains the
+given identifier.
 
-Returns a list of all objects in the database.  The return value is a list
-of references to pairs of type and name.  For example, if two objects
-existed in the database, both of type "keytab" and with values
-"host/example.com" and "foo", list_objects() would return:
+=item list_objects(TYPE, SEARCH)
+
+Returns a list of all objects matching a search type and string in the 
+database, or all objects in the database if no search information is 
+given.  The return value is a list of references to pairs of type and 
+name.  For example, if two objects existed in the database, both of type 
+"keytab" and with values "host/example.com" and "foo", list_objects() 
+with no arguments would return:
 
     ([ 'keytab', 'host/example.com' ], [ 'keytab', 'foo' ])
 
@@ -503,6 +513,14 @@ database containing no objects, the caller should call error().  error()
 is guaranteed to return the error message if there was an error and undef
 if there was no error.
 
+There are four types of searches currently.  'type' (with a given type)
+will return only those entries where the type matches the given type.
+'owner', with a given owner, will only return those objects owned by the
+given acl name.  'flag', with a given flag name, will only return those 
+items with a flag set to the given value.  'acl' operates like 'owner', 
+but will return only those objects that have the given acl name on any
+of the possible acl settings, not just owner.
+
 =item register_object (TYPE, CLASS)
 
 Register in the database a mapping from the object type TYPE to the class
diff --git a/perl/Wallet/Kadmin.pm b/perl/Wallet/Kadmin.pm
index 200136c..0a9bd43 100644
--- a/perl/Wallet/Kadmin.pm
+++ b/perl/Wallet/Kadmin.pm
@@ -120,6 +120,8 @@ calling valid_principal on the returned object -- this method is a shortcut
 in case we want to check validity without creating the object and worrying
 about proper setup.
 
+=back
+
 =head1 SEE ALSO
 
 kadmin(8), Wallet::Config(3), Wallet::Object::Keytab(3), wallet-backend(8)
diff --git a/server/wallet-admin b/server/wallet-admin
index 01fea5c..761288d 100755
--- a/server/wallet-admin
+++ b/server/wallet-admin
@@ -156,10 +156,10 @@ Before running C<initialize>, the wallet system has to be configured.  See
 Wallet::Config(3) for more details.  Depending on the database backend
 used, the database may also have to be created in advance.
 
-=item list (acls | objects)
+=item list (acls | objects) [ <searchtype> [ <arg> ... ] ]
 
-Returns a list of all ACLs or objects in the database.  ACLs will be
-listed in the form:
+Returns a list of ACLs or objects in the database.  ACLs will be listed 
+in the form:
 
     <name> (ACL ID: <id>)
 
@@ -171,6 +171,51 @@ be listed in the form:
 
 In both cases, there will be one line per ACL or object.
 
+If no searchtype is given, all the ACLs or objects in the database will
+be returned.  If a searchtype (and possible search arguments) are given,
+then the ACLs or objects will be limited to those that match the search.
+
+The currently supported object search types are:
+
+=over 4
+
+=item list objects type <type>
+
+Returns all objects of the given type.
+
+=item list objects flag <flag>
+
+Returns all objects which have the given flag set.
+
+=item list objects owner <acl name>
+
+Returns all objects owned by the given ACL name.
+
+=item list objects acl <acl name>
+
+Returns all objects for which the given ACL name has any permissions.
+This includes those objects owned by the ACL, but also those for which the
+ACL has get permissions, for example.
+
+=back
+
+The currently supported ACL search types are:
+
+=over 4
+
+=item list acls empty
+
+Returns all ACLs which have no entries, generally so that abandoned ACLs
+can be housekept.
+
+=item list acls entry <schema> <identifier>
+
+Returns all ACLs containing an entry with given schema and identifier.  
+The schema is used for an exact search, while the identifier given will 
+match any identifier containing that text, for flexibility.
+
+=back
+
 =item register (object | verifier) <type> <class>
 
 Registers an implementation of a wallet object or ACL verifier in the