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 <[email protected]> --- libraries/libapparmor/doc/Makefile.am | 2 +- libraries/libapparmor/doc/aa_policy_cache.pod | 125 ++++++++++++++++++++++++++ libraries/libapparmor/src/policy_cache.c | 6 +- 3 files changed, 129 insertions(+), 4 deletions(-) create mode 100644 libraries/libapparmor/doc/aa_policy_cache.pod diff --git a/libraries/libapparmor/doc/Makefile.am b/libraries/libapparmor/doc/Makefile.am index 6a48d99..67de347 100644 --- a/libraries/libapparmor/doc/Makefile.am +++ b/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_features.3 aa_kernel_interface.3 +man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2 aa_features.3 aa_kernel_interface.3 aa_policy_cache.3 PODS = $(subst .2,.pod,$(man_MANS)) $(subst .3,.pod,$(man_MANS)) diff --git a/libraries/libapparmor/doc/aa_policy_cache.pod b/libraries/libapparmor/doc/aa_policy_cache.pod new file mode 100644 index 0000000..b079f46 --- /dev/null +++ b/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 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 diff --git a/libraries/libapparmor/src/policy_cache.c b/libraries/libapparmor/src/policy_cache.c index 04086e7..f685f0a 100644 --- a/libraries/libapparmor/src/policy_cache.c +++ b/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) -- 2.1.4 -- AppArmor mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
