Add \brief command to file header to make doxygen happy.

[adu.git] / user.c

diff --git a/user.c b/user.c
index 1bdd34bbc9274ebe74ffd8d0401e9ecdae3cdf9e..8959c847b0b2069c76965850fc2acc07a8cfa097 100644 (file)
--- a/user.c
+++ b/user.c
@@ -4,7 +4,7 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
-/** \file user.c uid User and user ID handling. */
+/** \file user.c \brief User and user ID handling. */
 
 #include "adu.h"
 #include <dirent.h> /* readdir() */
@@ -29,6 +29,7 @@ struct uid_range {
        uint32_t high;
 };
 
+/** Iterate over all uid ranges. */
 #define FOR_EACH_UID_RANGE(ur, urs) for (ur = urs; ur->low <= ur->high; ur++)
 
 /** Flags for the user hash table. */
@@ -38,6 +39,7 @@ enum uid_info_flags {
        /** Whether this uid should be taken into account. */
        UI_FL_ADMISSIBLE = 2,
 };
+
 /*
  * Contains info for each user that owns at least one regular file.
  *
@@ -54,7 +56,7 @@ static uint32_t uid_hash_table_size;
 static int *uid_hash_table_sort_idx;
 
 /** The number of used slots in the hash table. */
-static uint32_t num_uids = 0;
+static uint32_t num_uids;
 
 /*
  * The columns of the per-user tables.
@@ -144,6 +146,15 @@ out:
        return ret;
 }
 
+/**
+ * Convert the --uid argument to an array of uid ranges.
+ *
+ * \param orig_arg The argument to the --uid option.
+ * \param ur Result pointer.
+ *
+ * Returns Negative on errors. On success, the number of uid ranges
+ * is returned.
+ */
 int parse_uid_arg(const char *orig_arg, struct uid_range **ur)
 {
        char *arg, **argv;
@@ -192,6 +203,22 @@ out:
        return ret;
 }
 
+/**
+ * Add each given user to the array of admissible users.
+ *
+ * \param users Array of user names to add.
+ * \param num_users Length of \a users.
+ * \param admissible_uids The users which are already admissible.
+ * \param num_uid_ranges The number of intervals of \a admissible_uids.
+ *
+ * For each given user, the function checks whether that user is already
+ * admissible, i.e. its uid is contained in one of the ranges given by \a
+ * admissible_uids. If it is, the function ignores that user. Otherwise, a new
+ * length-one range consisting of that uid only is appended to \a
+ * admissible_uids.
+ *
+ * \return Negative on errors, the new number of uid ranges on success.
+ */
 int append_users(char **users, int num_users,
                struct uid_range **admissible_uids, int num_uid_ranges)
 {
@@ -273,9 +300,23 @@ err:
        return ret;
 }
 
+/** Iterate over each user in the uid hash table. */
 #define FOR_EACH_USER(ui) for (ui = uid_hash_table; ui < \
        uid_hash_table + uid_hash_table_size; ui++)
 
+
+/**
+ * Execute the given function for each admissible user.
+ *
+ * \param func The function to execute.
+ * \param data Arbitrary pointer.
+ *
+ * This function calls \a func for each admissible user in the uid hash table.
+ * The \a data pointer is passed as the second argument to \a func.
+ *
+ * \return As soon as \a func returns a negative value, the loop is terminated
+ * and that negative value is returned. Otherwise, the function returns 1.
+ */
 int for_each_admissible_user(int (*func)(struct user_info *, void *),
                void *data)
 {
@@ -346,7 +387,7 @@ void close_user_tables(void)
 
 /*
  * We use a hash table of size s=2^uid_hash_bits to map the uids into the
- * interval [0..s]. Hash collisions are treated by open addressing, i.e.
+ * interval [0..s-1]. Hash collisions are treated by open addressing, i.e.
  * unused slots in the table are used to store different uids that hash to the
  * same slot.
  *
@@ -358,7 +399,7 @@ void close_user_tables(void)
  * An odd number is sufficient to make sure each entry of the hash table gets
  * probed for probe_num between 0 and s-1 because s is a power of two, hence
  * the second hash value has never a common divisor with the hash table size.
- * IOW: h is invertible in the ring [0..s].
+ * IOW: h is invertible in the ring [0..s-1].
  */
 static uint32_t double_hash(uint32_t uid, uint32_t probe_num)
 {
@@ -424,9 +465,8 @@ int open_admissible_user_tables(struct uid_range *admissible_uids)
        FOR_EACH_USER(ui) {
                int ret;
 
-               if (!ui_used(ui)) {
+               if (!ui_used(ui))
                        continue;
-               }
                if (!uid_is_admissible(ui->uid, admissible_uids)) {
                        DEBUG_LOG("uid %u is not admissible\n", ui->uid);
                        ui->flags &= ~UI_FL_ADMISSIBLE;