X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=select.c;h=7d1212c93cd63fa42d7f54bece7986b3cbf45e7c;hb=5008f98a8208d96c3c777476d6df7534c6d2ca49;hp=cd18beeb1e0f72e8bd8a10748f0f49fe0c5a9e4b;hpb=63cf7c8fbf05a53b58e1de1116ec2660b9cb7801;p=adu.git

diff --git a/select.c b/select.c
index cd18bee..7d1212c 100644
--- a/select.c
+++ b/select.c
@@ -4,7 +4,7 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
-/** \file select.c The select mode of adu. */
+/** \file select.c \brief The select mode of adu. */
 
 #include <dirent.h> /* readdir() */
 #include <sys/types.h>
@@ -20,6 +20,7 @@
 #include "user.h"
 #include "select.cmdline.h"
 
+/** \cond */
 /* global list */
 #define GLOBAL_LIST_ATOMS \
 	ATOM(size, SIZE) \
@@ -103,6 +104,8 @@ struct atom user_summary_atoms[] = {
 enum user_summary_atoms {USER_SUMMARY_ATOMS};
 #undef ATOM
 
+/** \endcond */
+
 struct global_list_info {
 	uint32_t count;
 	int ret;
@@ -854,6 +857,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();
@@ -877,9 +895,13 @@ out:
 	return ret;
 }
 
+/** Default format string for global_list mode. */
 #define GLOBAL_LIST_DFLT_FMT "%(size:r:8) %(files:r:8) %(dirname)\n"
+/** Default format string for global_summary mode. */
 #define GLOBAL_SUMMARY_DFLT_FMT "#directories: %(dirs), #files: %(files), size: %(size)\n\n"
+/** Default format string for user_list mode. */
 #define USER_LIST_DFLT_FMT "%(size:r:5) %(files:r:5) %(dirname)\n"
+/** Default format string for user_summary mode. */
 #define USER_SUMMARY_DFLT_FMT "%(pw_name:l:16) %(uid:r:5) %(dirs:r:5) %(files:r:5) %(size:r:5)\n"
 
 static int setup_format_string(char *fmt, struct format_info **fi)
@@ -917,7 +939,33 @@ static int setup_format_string(char *fmt, struct format_info **fi)
 	return parse_format_string(fmt, atoms, fi);
 }
 
-/* return: < 0: error, >0: OK, == 0: help given */
+/**
+ * Parse a given format string.
+ *
+ * \param string The format string to parse.
+ * \param params gengetopt parameters.
+ * \param admissible_uids The array of admissible uid ranges.
+ * \param fi The format info to be used with format_items().
+ *
+ * If \a string is not \p NULL, it is broken down into its components using
+ * \ref create_argv() and the resulting argument vector is passed together with
+ * \a params to gengetopt's command line parser. If --help or --detailed-help
+ * was specified in \a string, the corresponding help text is printed and the
+ * function returns zero.
+ *
+ * Otherwise, any --uid or --user options are parsed and transformed into an
+ * array of admissible uids which is returned via \a admissible_uids.
+ *
+ * Finally, the format string given by --format (or the default format string
+ * for the given select mode if no --format option was given in \a string) is
+ * parsed as well resulting in a format_info structure which is returned via
+ * \a fi. The caller uses the \a fi pointer later to format each output line.
+ *
+ * \return Negative on errors, zero if --help or --detailed-help was given,
+ * positive otherwise.
+ *
+ * \sa format_items().
+ */
 int parse_select_options(char *string, struct select_cmdline_parser_params *params,
 		struct uid_range **admissible_uids, struct format_info **fi)
 {
@@ -963,6 +1011,11 @@ help:
 	return 0;
 }
 
+/**
+ * Main function for select mode.
+ *
+ * \return Standard.
+ */
 int com_select(void)
 {
 	struct uid_range *admissible_uids = NULL;