Create a section 3 man page for the aa_features 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 | 13 ++- libraries/libapparmor/doc/aa_features.pod | 148 ++++++++++++++++++++++++++++++ libraries/libapparmor/src/features.c | 16 ++-- 3 files changed, 167 insertions(+), 10 deletions(-) create mode 100644 libraries/libapparmor/doc/aa_features.pod diff --git a/libraries/libapparmor/doc/Makefile.am b/libraries/libapparmor/doc/Makefile.am index 39d741d..d7aae8a 100644 --- a/libraries/libapparmor/doc/Makefile.am +++ b/libraries/libapparmor/doc/Makefile.am @@ -5,9 +5,9 @@ PODCHECKER = podchecker if ENABLE_MAN_PAGES -man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2 +man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2 aa_features.3 -PODS = $(subst .2,.pod,$(man_MANS)) +PODS = $(subst .2,.pod,$(man_MANS)) $(subst .3,.pod,$(man_MANS)) EXTRA_DIST = $(man_MANS) $(PODS) @@ -23,4 +23,13 @@ CLEANFILES = $(man_MANS) --stderr \ $< > $@ +%.3: %.pod + $(PODCHECKER) -warnings -warnings $< + $(POD2MAN) \ + --section=3 \ + --release="AppArmor $(VERSION)" \ + --center="AppArmor" \ + --stderr \ + $< > $@ + endif diff --git a/libraries/libapparmor/doc/aa_features.pod b/libraries/libapparmor/doc/aa_features.pod new file mode 100644 index 0000000..f971a9e --- /dev/null +++ b/libraries/libapparmor/doc/aa_features.pod @@ -0,0 +1,148 @@ +# 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_features - an opaque object representing a set of AppArmor kernel features + +aa_features_new - create a new aa_features object based on a path + +aa_features_new_from_string - create a new aa_features object based on a string + +aa_features_new_from_kernel - create a new aa_features object based on the current kernel + +aa_features_ref - increments the ref count of an aa_features object + +aa_features_unref - decrements the ref count and frees the aa_features object when 0 + +aa_features_write_to_file - write a string representation of an aa_features object to a file + +aa_features_is_equal - equality test for two aa_features objects + +aa_features_supports - provides aa_features object support status + +=head1 SYNOPSIS + +B<#include E<lt>sys/apparmor.hE<gt>> + +B<typedef struct aa_features aa_features;> + +B<int aa_features_new(aa_features **features, int dirfd, const char *path);> + +B<int aa_features_new_from_string(aa_features **features, const char *string, size_t size);> + +B<int aa_features_new_from_kernel(aa_features **features);> + +B<aa_features *aa_features_ref(aa_features *features);> + +B<void aa_features_unref(aa_features *features);> + +B<int aa_features_write_to_file(aa_features *features, int dirfd, const char *path);> + +B<bool aa_features_is_equal(aa_features *features1, aa_features *features2);> + +B<bool aa_features_supports(aa_features *features, const char *str);> + +Link with B<-lapparmor> when compiling. + +=head1 DESCRIPTION + +The I<aa_features> object contains information about the AppArmor features +supported by a kernel. The feature support information is based upon the files +AppArmor represents in securityfs, which is typically found at +/sys/kernel/security/apparmor/features/. That information may be parsed and +turned into a string or flat file in order to represent a set of features of +kernel that is not currently running. + +The aa_features_new() function creates an I<aa_features> object based upon a +directory file descriptor and path. The I<path> can point to a file or +directory. See the openat(2) man page for examples of I<dirfd> and I<path>. The +allocated I<features> object must be freed using aa_features_unref(). + +The aa_features_new_from_string() function is similar except that it accepts a +NUL-terminated string representation of the AppArmor features as the I<string> +argument. The length of the features string, not counting the NUL-terminator, +must be specified as the I<size> argument. The allocated I<features> object +must be freed using aa_features_unref(). + +The aa_features_new_from_kernel() function creates an I<aa_features> object +from the current running kernel. The allocated I<features> object must be freed +using aa_features_unref(). + +aa_features_ref() increments the reference count on the I<features> object. + +aa_features_unref() decrements the reference count on the I<features> object +and releases all corresponding resources when the reference count reaches zero. + +The aa_features_write_to_file() function writes a string representation of the +I<features> object to the file specified by the I<dirfd> and I<path> +combination. + +aa_features_is_equal() can be used to detect if the I<features1> and +I<features2> objects are equal. The definition of equality is private to +libapparmor and may be changed in ways that do not break backward +compatibility. + +The aa_features_supports() function can be used to query the I<features> object +to determine if a feature is supported. The I<str> argument should be equal to +the path, relative to the "apparmor/features/" directory of securityfs, of the +feature to query. For example, to test if policy version 6 is supported, I<str> +would be "policy/versions/v6". + +=head1 RETURN VALUE + +The aa_features_new() family of functions return 0 on success and I<*features> +will point to an I<aa_features> object that must be freed by +aa_features_unref(). -1 is returned on error, with errno set appropriately, and +I<*features> will be set to NULL. + +aa_features_ref() returns the value of I<features>. + +aa_features_write_to_file() returns 0 on success. -1 is returned on error, with +errno set appropriately. + +aa_features_is_equal() returns true if I<features1> and I<features2> are equal +and false if they are not equal. + +aa_features_supports() returns true if the feature represented by I<str> is +supported and false if it is not supported. + +=head1 ERRORS + +The errno value will be set according to the underlying error in the +I<aa_features> family of functions that return -1 on error. + +=head1 NOTES + +All aa_features 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 + +openat(2) and L<http://wiki.apparmor.net>. + +=cut diff --git a/libraries/libapparmor/src/features.c b/libraries/libapparmor/src/features.c index 12a708b..4cec6cb 100644 --- a/libraries/libapparmor/src/features.c +++ b/libraries/libapparmor/src/features.c @@ -356,7 +356,7 @@ static bool walk_one(const char **str, const struct component *component, } /** - * aa_features_new - create a new features based on a path + * aa_features_new - create a new aa_features object based on a path * @features: will point to the address of an allocated and initialized * aa_features object upon success * @dirfd: directory file descriptor or AT_FDCWD (see openat(2)) @@ -400,7 +400,7 @@ int aa_features_new(aa_features **features, int dirfd, const char *path) } /** - * aa_features_new_from_string - create a new features based on a string + * aa_features_new_from_string - create a new aa_features object based on a string * @features: will point to the address of an allocated and initialized * aa_features object upon success * @string: a NUL-terminated string representation of features @@ -435,7 +435,7 @@ int aa_features_new_from_string(aa_features **features, } /** - * aa_features_new_from_kernel - create a new features based on the current kernel + * aa_features_new_from_kernel - create a new aa_features object based on the current kernel * @features: will point to the address of an allocated and initialized * aa_features object upon success * @@ -448,7 +448,7 @@ int aa_features_new_from_kernel(aa_features **features) } /** - * aa_features_ref - increments the ref count of a features + * aa_features_ref - increments the ref count of an aa_features object * @features: the features * * Returns: the features @@ -460,7 +460,7 @@ aa_features *aa_features_ref(aa_features *features) } /** - * aa_features_unref - decrements the ref count and frees the features when 0 + * aa_features_unref - decrements the ref count and frees the aa_features object when 0 * @features: the features (can be NULL) */ void aa_features_unref(aa_features *features) @@ -470,7 +470,7 @@ void aa_features_unref(aa_features *features) } /** - * aa_features_write_to_file - write a string representation to a file + * aa_features_write_to_file - write a string representation of an aa_features object to a file * @features: the features * @dirfd: directory file descriptor or AT_FDCWD (see openat(2)) * @path: the path to write to @@ -506,7 +506,7 @@ int aa_features_write_to_file(aa_features *features, } /** - * aa_features_is_equal - equality test for two features + * aa_features_is_equal - equality test for two aa_features objects * @features1: the first features (can be NULL) * @features2: the second features (can be NULL) * @@ -519,7 +519,7 @@ bool aa_features_is_equal(aa_features *features1, aa_features *features2) } /** - * aa_features_supports - provides features support status + * aa_features_supports - provides aa_features object support status * @features: the features * @str: the string representation of a feature to check * -- 2.1.4 -- AppArmor mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
