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>

diff --git a/libsubid/api.c b/libsubid/api.c
index 737e1c8b26ea6acd1237d52d1a1703797a0c3649..a1b5bb3f08e810cd1476d6f818fe22f8911a8f6c 100644 (file)
--- a/libsubid/api.c
+++ b/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)

diff --git a/libsubid/api.h b/libsubid/api.h
deleted file mode 100644 (file)
index 97b04e2..0000000
--- a/libsubid/api.h
+++ /dev/null
@@ -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);

diff --git a/libsubid/subid.h b/libsubid/subid.h
index 2f27ad8ae3da9ee32d66c8b84aba4367b2125c8a..769463f6e41ecf3508275518074f34b590b251db 100644 (file)
--- a/libsubid/subid.h
+++ b/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

diff --git a/src/free_subid_range.c b/src/free_subid_range.c
index de6bc58fdb7c2772c18ab6f21199f88e885ca637..3701a262f7de44f63d790ae4a5e920f7d0bb9e1a 100644 (file)
--- a/src/free_subid_range.c
+++ b/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"
 

diff --git a/src/get_subid_owners.c b/src/get_subid_owners.c
index a4385540383f3021676287cb3c79a3ccfd1cda93..409e3fea364c680a177b81446f035c9c51434513 100644 (file)
--- a/src/get_subid_owners.c
+++ b/src/get_subid_owners.c
@@ -1,5 +1,5 @@
 #include <stdio.h>
-#include "api.h"
+#include "subid.h"
 #include "stdlib.h"
 #include "prototypes.h"
 

diff --git a/src/list_subid_ranges.c b/src/list_subid_ranges.c
index 440ef911b5db4dafe5aad800a3f328f153949e00..21b2c1923c00793624e91e8d713e07f51421a1ad 100644 (file)
--- a/src/list_subid_ranges.c
+++ b/src/list_subid_ranges.c
@@ -1,5 +1,5 @@
 #include <stdio.h>
-#include "api.h"
+#include "subid.h"
 #include "stdlib.h"
 #include "prototypes.h"
 

diff --git a/src/new_subid_range.c b/src/new_subid_range.c
index 6d7b033b253abad9a30c140e5eb9b133bc735b49..dde196b324beaa64598a11d6ffa6c366596b3a5a 100644 (file)
--- a/src/new_subid_range.c
+++ b/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"