clean up libsubid headers

Move libsubid/api.h into libsubid/subid.h, and document the api in subid.h

Signed-off-by: Serge Hallyn <serge@hallyn.com>

libsubid/api.c

@@ -36,7 +36,7 @@
 #include <stdbool.h>
 #include "subordinateio.h"
 #include "idmapping.h"
-#include "api.h"
+#include "subid.h"
 
 static
 int get_subid_ranges(const char *owner, enum subid_type id_type, struct subordinate_range ***ranges)

libsubid/api.h

@@ -1,17 +0,0 @@
-#include "subid.h"
-#include <stdbool.h>
-
-int get_subuid_ranges(const char *owner, struct subordinate_range ***ranges);
-int get_subgid_ranges(const char *owner, struct subordinate_range ***ranges);
-void subid_free_ranges(struct subordinate_range **ranges, int count);
-
-int get_subuid_owners(uid_t uid, uid_t **owner);
-int get_subgid_owners(gid_t gid, uid_t **owner);
-
-/* range should be pre-allocated with owner and count filled in, start is
- * ignored, can be 0 */
-bool grant_subuid_range(struct subordinate_range *range, bool reuse);
-bool grant_subgid_range(struct subordinate_range *range, bool reuse);
-
-bool ungrant_subuid_range(struct subordinate_range *range);
-bool ungrant_subgid_range(struct subordinate_range *range);

libsubid/subid.h

@@ -21,5 +21,110 @@ enum subid_status {
 	SUBID_STATUS_ERROR = 3,
 };
 
+/*
+ * get_subuid_ranges: return a list of UID ranges for a user
+ *
+ * @owner: username being queried
+ * @ranges: a pointer to a subordinate range ** in which the result will be
+ *          returned.
+ *
+ * returns: number of ranges found, ir < 0 on error.
+ */
+int get_subuid_ranges(const char *owner, struct subordinate_range ***ranges);
+
+/*
+ * get_subgid_ranges: return a list of GID ranges for a user
+ *
+ * @owner: username being queried
+ * @ranges: a pointer to a subordinate range ** in which the result will be
+ *          returned.
+ *
+ * returns: number of ranges found, ir < 0 on error.
+ */
+int get_subgid_ranges(const char *owner, struct subordinate_range ***ranges);
+
+/*
+ * subid_free_ranges: free an array of subordinate_ranges returned by either
+ *                    get_subuid_ranges() or get_subgid_ranges().
+ *
+ * @ranges: the ranges to free
+ * @count: the number of ranges in @ranges
+ */
+void subid_free_ranges(struct subordinate_range **ranges, int count);
+
+/*
+ * get_subuid_owners: return a list of uids to which the given uid has been
+ *                    delegated.
+ *
+ * @uid: The subuid being queried
+ * @owners: a pointer to an array of uids into which the results are placed.
+ *          The returned array must be freed by the caller.
+ *
+ * Returns the number of uids returned, or < 0 on error.
+ */
+int get_subuid_owners(uid_t uid, uid_t **owner);
+
+/*
+ * get_subgid_owners: return a list of uids to which the given gid has been
+ *                    delegated.
+ *
+ * @uid: The subgid being queried
+ * @owners: a pointer to an array of uids into which the results are placed.
+ *          The returned array must be freed by the caller.
+ *
+ * Returns the number of uids returned, or < 0 on error.
+ */
+int get_subgid_owners(gid_t gid, uid_t **owner);
+
+/*
+ * grant_subuid_range: assign a subuid range to a user
+ *
+ * @range: pointer to a struct subordinate_range detailing the UID range
+ *         to allocate.  ->owner must be the username, and ->count must be
+ *         filled in.  ->start is ignored, and will contain the start
+ *         of the newly allocated range, upon success.
+ *
+ * Returns true if the delegation succeeded, false otherwise.  If true,
+ * then the range from (range->start, range->start + range->count) will
+ * be delegated to range->owner.
+ */
+bool grant_subuid_range(struct subordinate_range *range, bool reuse);
+
+/*
+ * grant_subsid_range: assign a subgid range to a user
+ *
+ * @range: pointer to a struct subordinate_range detailing the GID range
+ *         to allocate.  ->owner must be the username, and ->count must be
+ *         filled in.  ->start is ignored, and will contain the start
+ *         of the newly allocated range, upon success.
+ *
+ * Returns true if the delegation succeeded, false otherwise.  If true,
+ * then the range from (range->start, range->start + range->count) will
+ * be delegated to range->owner.
+ */
+bool grant_subgid_range(struct subordinate_range *range, bool reuse);
+
+/*
+ * ungrant_subuid_range: remove a subuid allocation.
+ *
+ * @range: pointer to a struct subordinate_range detailing the UID allocation
+ *         to remove.
+ *
+ * Returns true if successful, false if it failed, for instance if the
+ * delegation did not exist.
+ */
+bool ungrant_subuid_range(struct subordinate_range *range);
+
+/*
+ * ungrant_subuid_range: remove a subgid allocation.
+ *
+ * @range: pointer to a struct subordinate_range detailing the GID allocation
+ *         to remove.
+ *
+ * Returns true if successful, false if it failed, for instance if the
+ * delegation did not exist.
+ */
+bool ungrant_subgid_range(struct subordinate_range *range);
+
 #define SUBID_NFIELDS 3
 #endif

src/free_subid_range.c

@@ -1,6 +1,6 @@
 #include <stdio.h>
 #include <unistd.h>
-#include "api.h"
+#include "subid.h"
 #include "stdlib.h"
 #include "prototypes.h"
 

src/get_subid_owners.c

@@ -1,5 +1,5 @@
 #include <stdio.h>
-#include "api.h"
+#include "subid.h"
 #include "stdlib.h"
 #include "prototypes.h"
 

src/list_subid_ranges.c

@@ -1,5 +1,5 @@
 #include <stdio.h>
-#include "api.h"
+#include "subid.h"
 #include "stdlib.h"
 #include "prototypes.h"
 

src/new_subid_range.c

@@ -1,6 +1,6 @@
 #include <stdio.h>
 #include <unistd.h>
-#include "api.h"
+#include "subid.h"
 #include "stdlib.h"
 #include "prototypes.h"