add man page for aa_query_label

Signed-off-by: John Johansen <john.johansen@canonical.com>
Acked-by: Tyler Hicks <tyhicks@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
+man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2 aa_splitcon.3 aa_query_label.2
 
 PODS = $(subst .2,.pod,$(man_MANS)) $(subst .3,.pod,$(man_MANS))
 

libraries/libapparmor/doc/aa_query_label.pod

@@ -0,0 +1,107 @@
+# 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_query_label - query access permission associated with a label
+
+=head1 SYNOPSIS
+
+B<#include E<lt>sys/apparmor.hE<gt>>
+
+B<int aa_query_label((uint32_t mask, char *query, size_t size,
+		int *allowed, int *audited);>
+
+Link with B<-lapparmor> when compiling.
+
+=head1 DESCRIPTION
+
+The aa_query_label function fetches the current permissions granted by the
+specified I<label> in the I<query> string.
+
+The query is a raw binary formatted query, containing the label and
+permission query to make. The returned I<allowed> and I<audited> values are
+interpreted boolean values, simple stating whether the query is allowed and
+if it is audited.
+
+The mask of the query string is a bit mask of permissions to query and is
+class type dependent (see AA_CLASS_xxx) entries in I<sys/apparmor.h>.
+
+The format of the query string is also dependent on the B<AA_CLASS> and as
+such the the aa_query_xxx helper functions should usually be used instead
+of directly using I<aa_query_label>. If directly using the interface the
+I<query> string is required to have a header of B<AA_QUERY_CMD_LABEL_SIZE>
+that will be used by I<aa_query_label>.
+
+=head1 RETURN VALUE
+
+On success 0 is returned, and the I<allowed> and I<audited> parameters
+contain a boolean value of 0 not allowed/audited or 1 allowed/audited. On
+error, -1 is returned, and errno(3) is set appropriately.
+
+=head1 ERRORS
+
+=over 4
+
+=item B<EINVAL>
+
+The requested I<mask> is empty.
+
+The I<size> of the query is E<lt> the query B<AA_QUER?Y_CMD_LABEL_SIZE>
+
+The apparmor kernel module is not loaded or the he kernel interface access
+interface is not available
+
+=item B<ENOMEM>
+
+Insufficient memory was available.
+
+=item B<EACCES>
+
+Access to the specified I<label> or query interface was denied.
+
+=item B<ENOENT>
+
+The specified I<label> does not exist or is not visible.
+
+=item B<ERANGE>
+
+The confinement data is too large to fit in the supplied buffer.
+
+=back
+
+=head1 NOTES
+
+The label permissions returned are only valid for the time of the
+query and can change at any point in the future.
+
+=head1 BUGS
+
+None known. If you find any, please report them at
+L<https://bugs.launchpad.net/apparmor/+filebug>.
+
+=head1 SEE ALSO
+
+apparmor(7), apparmor.d(5), apparmor_parser(8), aa_getcon(2), aa_splitcon(3)
+and L<http://wiki.apparmor.net>.
+
+=cut