libapparmor: Create a man page for aa_policy_cache

Create a section 3 man page for the aa_policy_cache family of functions.
Additionally, update the in-code descriptions to match the descriptions
in the man page.

Signed-off-by: Tyler Hicks <tyhicks@canonical.com>
Acked-by: John Johansen <john.johansen@canonical.com>

libraries/libapparmor/doc/Makefile.am

@@ -5,7 +5,7 @@ PODCHECKER = podchecker
 
 if ENABLE_MAN_PAGES
 
-man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2 aa_splitcon.3 aa_query_label.2 aa_features.3 aa_kernel_interface.3
+man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2 aa_splitcon.3 aa_query_label.2 aa_features.3 aa_kernel_interface.3 aa_policy_cache.3
 
 PODS = $(subst .2,.pod,$(man_MANS)) $(subst .3,.pod,$(man_MANS))
 

libraries/libapparmor/doc/aa_policy_cache.pod

@@ -0,0 +1,125 @@
+# This publication is intellectual property of Canonical Ltd. Its contents
+# can be duplicated, either in part or in whole, provided that a copyright
+# label is visibly located on each copy.
+#
+# All information found in this book has been compiled with utmost
+# attention to detail. However, this does not guarantee complete accuracy.
+# Neither Canonical Ltd, the authors, nor the translators shall be held
+# liable for possible errors or the consequences thereof.
+#
+# Many of the software and hardware descriptions cited in this book
+# are registered trademarks. All trade names are subject to copyright
+# restrictions and may be registered trade marks. Canonical Ltd.
+# essentially adhere to the manufacturer's spelling.
+#
+# Names of products and trademarks appearing in this book (with or without
+# specific notation) are likewise subject to trademark and trade protection
+# laws and may thus fall under copyright restrictions.
+#
+
+
+=pod
+
+=head1 NAME
+
+aa_policy_cache - an opaque object representing an AppArmor policy cache
+
+aa_policy_cache_new - create a new aa_policy_cache object from a path
+
+aa_policy_cache_ref - increments the ref count of an aa_policy_cache object
+
+aa_policy_cache_unref - decrements the ref count and frees the aa_policy_cache object when 0
+
+aa_policy_cache_remove - removes all policy cache files under a path
+
+aa_policy_cache_replace_all - performs a kernel policy replacement of all cached policies
+
+=head1 SYNOPSIS
+
+B<#include E<lt>sys/apparmor.hE<gt>>
+
+B<typedef struct aa_policy_cache aa_policy_cache;>
+
+B<int aa_policy_cache_new(aa_policy_cache **policy_cache, aa_features *kernel_features, int dirfd, const char *path, uint16_t max_caches);>
+
+B<aa_policy_cache *aa_policy_cache_ref(aa_policy_cache *policy_cache);>
+
+B<void aa_policy_cache_unref(aa_policy_cache *policy_cache);>
+
+B<int aa_policy_cache_remove(int dirfd, const char *path);>
+
+B<int aa_policy_cache_replace_all(aa_policy_cache *policy_cache, aa_kernel_interface *kernel_interface);>
+
+Link with B<-lapparmor> when compiling.
+
+=head1 DESCRIPTION
+
+The I<aa_policy_cache> object contains information about a set of AppArmor
+policy cache files. The policy cache files are the binary representation of a
+human-readable AppArmor profile. The binary representation is the form that is
+loaded into the kernel.
+
+The aa_policy_cache_new() function creates an I<aa_policy_cache> object based
+upon a directory file descriptor and path. The I<path> must point to a
+directory. See the openat(2) man page for examples of I<dirfd> and I<path>. If
+I<kernel_features> is NULL, then the features of the current kernel are used.
+When specifying a valid I<kernel_features> object, it must be the compatible
+with the features of the kernel of interest. The value of I<max_caches> should
+be equal to the number of caches that should be allowed before old caches are
+automatically reaped. The definition of what is considered to be an old cache
+is private to libapparmor. Specifying 0 means that no new caches should be
+created and only existing, valid caches may be used. Specifying UINT16_MAX
+means that a new cache may be created and that the reaping of old caches is
+disabled. The allocated I<aa_policy_cache> object must be freed using
+aa_policy_cache_unref().
+
+aa_policy_cache_ref() increments the reference count on the I<policy_cache>
+object.
+
+aa_policy_cache_unref() decrements the reference count on the I<policy_cache>
+object and releases all corresponding resources when the reference count
+reaches zero.
+
+The aa_policy_cache_remove() function deletes all of the policy cache files
+based upon a directory file descriptor and path. The I<path> must point to a 
+directory. See the openat(2) man page for examples of I<dirfd> and I<path>.
+
+The aa_policy_cache_replace_all() function can be used to perform a policy
+replacement of all of the cache policies in the cache directory represented by
+the I<policy_cache> object. If I<kernel_interface> is NULL, then the current
+kernel interface is used. When specifying a valid I<kernel_interface> object,
+it must be the interface of the currently running kernel.
+
+=head1 RETURN VALUE
+
+The aa_policy_cache_new() function returns 0 on success and I<*policy_cache>
+will point to an I<aa_policy_cache> object that must be freed by
+aa_policy_cache_unref(). -1 is returned on error, with errno set appropriately,
+and I<*policy_cache> will be set to NULL.
+
+aa_policy_cache_ref() returns the value of I<policy_cache>.
+
+aa_policy_cache_remove() and aa_policy_cache_replace_all() return 0 on success.
+-1 is returned on error, with errno set appropriately.
+
+=head1 ERRORS
+
+The errno value will be set according to the underlying error in the
+I<aa_policy_cache> family of functions that return -1 on error.
+
+=head1 NOTES
+
+All aa_policy_cache functions described above are present in libapparmor
+version 2.10 and newer.
+
+=head1 BUGS
+
+None known. If you find any, please report them at
+L<https://bugs.launchpad.net/apparmor/+filebug>.
+
+=head1 SEE ALSO
+
+aa_features(3), aa_kernel_interface(3), openat(2) and
+L<http://wiki.apparmor.net>.
+
+=cut

libraries/libapparmor/src/policy_cache.c

@@ -113,7 +113,7 @@ static int replace_all_cb(int dirfd unused, const char *name, struct stat *st,
 }
 
 /**
- * aa_policy_cache_new - create a new policy_cache from a path
+ * aa_policy_cache_new - create a new aa_policy_cache object from a path
  * @policy_cache: will point to the address of an allocated and initialized
  *                aa_policy_cache_new object upon success
  * @kernel_features: features representing a kernel (may be NULL if you want to
@@ -201,7 +201,7 @@ open:
 }
 
 /**
- * aa_policy_cache_ref - increments the ref count of a policy_cache
+ * aa_policy_cache_ref - increments the ref count of an aa_policy_cache object
  * @policy_cache: the policy_cache
  *
  * Returns: the policy_cache
@@ -213,7 +213,7 @@ aa_policy_cache *aa_policy_cache_ref(aa_policy_cache *policy_cache)
 }
 
 /**
- * aa_policy_cache_unref - decrements the ref count and frees the policy_cache when 0
+ * aa_policy_cache_unref - decrements the ref count and frees the aa_policy_cache object when 0
  * @policy_cache: the policy_cache (can be NULL)
  */
 void aa_policy_cache_unref(aa_policy_cache *policy_cache)