[apparmor] [PATCH v2 12/14] libapparmor: Create a man page for aa_features
Tyler Hicks
tyhicks at canonical.com
Thu Apr 2 15:17:49 UTC 2015
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 <tyhicks at canonical.com>
---
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
More information about the AppArmor
mailing list