Merge commit 'fml/master'

diff --git a/select.c b/select.c
index 209bf144a9e99e1bc2a27e67139459a9b2e6f302..5fd763c1b104cc519e0a06af08adddf3451df86e 100644 (file)
--- a/select.c
+++ b/select.c
@@ -854,6 +854,21 @@ open_file:
        return 1;
 }
 
+/**
+ * Execute a select query.
+ *
+ * \param admissible_uids User IDs to take into account.
+ * \param fi Format information.
+ *
+ * Called once in select mode or for each \a run command in interactive mode.
+ *
+ * Open the output stream and the dir table if not already open. For each
+ * admissible uid, the user table is opened if necessary. After these
+ * preparations, the output according to \a select_mode and \a fi is written to
+ * the output stream.
+ *
+ * \return Standard.
+ */
 int run_select_query(struct uid_range *admissible_uids, struct format_info *fi)
 {
        int ret = open_output_stream();
@@ -963,6 +978,11 @@ help:
        return 0;
 }
 
+/**
+ * Main function for select mode.
+ *
+ * \return Standard.
+ */
 int com_select(void)
 {
        struct uid_range *admissible_uids = NULL;

diff --git a/string.c b/string.c
index d42a31b5cb84df53ea8c6d3efed7f5d8f5c4c4af..07dd8459cda272666a4714941549d68bec1cc9b9 100644 (file)
--- a/string.c
+++ b/string.c
@@ -12,7 +12,7 @@
 #include "error.h"
 
 /**
- * Paraslash's version of realloc().
+ * Adu's version of realloc().
  *
  * \param p Pointer to the memory block, may be \p NULL.
  * \param size The desired new size.
@@ -41,7 +41,7 @@ __must_check __malloc void *adu_realloc(void *p, size_t size)
 }
 
 /**
- * Paraslash's version of malloc().
+ * Adu's version of malloc().
  *
  * \param size The desired new size.
  *
@@ -66,7 +66,7 @@ __must_check __malloc void *adu_malloc(size_t size)
 }
 
 /**
- * Paraslash's version of calloc().
+ * Adu's version of calloc().
  *
  * \param size The desired new size.
  *
@@ -86,7 +86,7 @@ __must_check __malloc void *adu_calloc(size_t size)
 }
 
 /**
- * Paraslash's version of strdup().
+ * Adu's version of strdup().
  *
  * \param s The string to be duplicated.
  *

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;