Add missing source code documentation of user.c.

This completes the documentation of user.c.

diff --git a/user.c b/user.c
index 8959c847b0b2069c76965850fc2acc07a8cfa097..bde47a7e79b87cc50d5813361d13cfc86746f272 100644 (file)
--- a/user.c
+++ b/user.c
@@ -337,9 +337,16 @@ int for_each_admissible_user(int (*func)(struct user_info *, void *),
        return 1;
 }
 
+/** Prime number used for calculating the slot for an uid. */
 #define PRIME1 0xb11924e1
+/** Prime number used for probe all slots. */
 #define PRIME2 0x01000193
 
+/**
+ * Create a hash table large enough of given size.
+ *
+ * \param bits Sets the maximal number of hash table entries to ^bits.
+ */
 void create_hash_table(unsigned bits)
 {
        int i;
@@ -352,6 +359,12 @@ void create_hash_table(unsigned bits)
                uid_hash_table_sort_idx[i] = i;
 }
 
+/**
+ * Close all open user tables and destroy the uid hash table.
+ *
+ * For each used slot in the uid hash table, close the osl user table if it is
+ * open.  Finally, free the uid hash table.
+ */
 void close_user_tables(void)
 {
        struct user_info *ui;
@@ -421,6 +434,19 @@ static struct user_info *lookup_uid(uint32_t uid)
        return NULL;
 }
 
+/**
+ * Create and open a osl table for the given uid.
+ *
+ * \param uid The user ID.
+ * \param ui_ptr Result pointer
+ *
+ * Find out whether \a uid already exists in the uid hash table.  If yes, just
+ * return the user info struct via \a ui_ptr. Otherwise, insert \a uid into the
+ * uid hash table, create and open the osl user table and also return the user
+ * info struct via \a ui_ptr.
+ *
+ * \return Standard.
+ */
 int create_user_table(uint32_t uid, struct user_info **ui_ptr)
 {
        struct user_info *ui = lookup_uid(uid);
@@ -449,6 +475,15 @@ static int comp_wrapper(const void *a, const void *b)
        return hash_table_comparator(x, y);
 }
 
+/**
+ * Sort the hash table according to a given comparator.
+ *
+ * \param comp The comparator.
+ *
+ * The comparator is a user-defined function which must return 1, 0, or -1.
+ *
+ * \sa qsort(3).
+ */
 void sort_hash_table(int (*comp)(struct user_info *, struct user_info *))
 {
        hash_table_comparator = comp;
@@ -456,6 +491,21 @@ void sort_hash_table(int (*comp)(struct user_info *, struct user_info *))
                sizeof(*uid_hash_table_sort_idx), comp_wrapper);
 }
 
+/**
+ * Open the osl tables for all admissible uids.
+ *
+ * \param admissible_uids Determines which uids are considered admissible.
+ *
+ * Each slot in the hash table contains, among other information, a bit which
+ * specifies whether the uid of the slot is admissible in the current context.
+ *
+ * This function iterates over all entries in the hash table and checks for
+ * each used slot whether the corresponding uid is admissible with respect to
+ * \a admissible_uids. If so, it sets the admissible bit for this slot and
+ * opens the osl table of the uid.
+ *
+ * \return Stamdard.
+ */
 int open_admissible_user_tables(struct uid_range *admissible_uids)
 {
        struct user_info *ui;
@@ -482,6 +532,18 @@ int open_admissible_user_tables(struct uid_range *admissible_uids)
        return 1;
 }
 
+/**
+ * Read the file of all possible uids.
+ *
+ * This is called from select/interactive mode. First a large hash table, large
+ * enough to store all uids contained in the uid file is created. Next, the
+ * uids are read from the uid file which was created during the creation of the
+ * database and each uid is inserted into the hash table.
+ *
+ * \sa write_uid_file().
+ *
+ * \return Standard.
+ */
 int read_uid_file(void)
 {
        size_t size;
@@ -524,6 +586,18 @@ out:
        return ret;
 }
 
+/**
+ * Write the list of uids to permanent storage.
+ *
+ * This is called from create mode after the dir table and all uer tables have
+ * been created. The file simply contains the list of all uids that own at
+ * least one regular file in the base directory and hence an osl table for this
+ * uid exists.
+ *
+ * \sa read_uid_file().
+ *
+ * \return Standard.
+ */
 int write_uid_file(void)
 {
        char *buf, *p, *filename;