From: Andre Noll Date: Sat, 22 Nov 2008 22:38:39 +0000 (+0100) Subject: Merge commit 'fml/master' X-Git-Tag: v0.1.0~23 X-Git-Url: http://git.tuebingen.mpg.de/?p=adu.git;a=commitdiff_plain;h=22a0aa79753b19604a6fa4273f1479ef71dbf06d;hp=44bb864e9d02f765064645b4e70d48b8c8113c48 Merge commit 'fml/master' --- diff --git a/adu.c b/adu.c index b8c7b68..dd74ca4 100644 --- a/adu.c +++ b/adu.c @@ -13,7 +13,6 @@ * - User handling: \ref user.c * - Error handling: \ref error.h * - Library-type functions: \ref fd.c, \ref format.c, \ref string.c, \ref portable_io.h - * - Generated files: \ref cmdline.h, \ref select.cmdline.h */ #include "adu.h" @@ -32,7 +31,7 @@ DEFINE_ERRLIST; /** - * The error code of the last osl library function. + * The error code of the last called osl library function. * * \sa osl(). */ diff --git a/adu.h b/adu.h index c67dd6b..5e99709 100644 --- a/adu.h +++ b/adu.h @@ -41,18 +41,6 @@ /** Log messages with lower priority than that will not be compiled in. */ #define COMPILE_TIME_LOGLEVEL 0 -/** - * A variant of static inline that requires the object being documented. - * - * If doxygen finds the \p static keyword in any context, that part will not be - * included in the documentation. However, we want static inline functions in - * header files to be documented while static functions in C files and - * statically declared variables should be left out. As a workaround for this - * flaw we use \p _static_inline_ for static inline functions declared in - * header files. - */ -#define _static_inline_ static inline - /** \cond */ #if DEBUG > COMPILE_TIME_LOGLEVEL #define DEBUG_LOG(f,...) __log(DEBUG, "%s: " f, __FUNCTION__, ## __VA_ARGS__) diff --git a/gcc-compat.h b/gcc-compat.h index df80001..ec24db9 100644 --- a/gcc-compat.h +++ b/gcc-compat.h @@ -4,28 +4,70 @@ * Licensed under the GPL v2. For licencing details see COPYING. */ -# define inline inline __attribute__ ((always_inline)) -# define __noreturn __attribute__ ((noreturn)) -# define __malloc __attribute__ ((malloc)) +/** \file gcc-compat.h Compatibility defines and macros. */ + +/** We want you-asked-for-it-you-got-it behavior. */ +# define inline inline __attribute__ ((always_inline)) + +/** Using \p __malloc for malloc-type functions often improves optimization. */ +# define __malloc __attribute__ ((malloc)) + +/** + * This allows to enable gcc's -Wunused messages. + * + * This gcc option can print warnings that can not be avoided easily. For + * example when using an array of (structures containing) function pointers. + * If not all the functions (handlers) use all arguments, gcc will print + * a warning. + * + * Marking those few unused function parameters with \p __a_unused to supress + * the gcc warnings allows us to get a clean build _and_ the benefit of the + * warning in other cases where we do care about unused parameters. + */ # define __a_unused __attribute__ ((unused)) + +/** The result \a x is expected to be non-zero. */ # define likely(x) __builtin_expect (!!(x), 1) +/** The result \a x is expected to be zero (or \p NULL). */ # define unlikely(x) __builtin_expect (!!(x), 0) -/* - * p is the number of the "format string" parameter, and q is - * the number of the first variadic parameter + +/** + * Let gcc check format strings also for our own functions. + * + * Functions marked with \p __printf will be cheked by gcc for format string + * bugs, just like printf() if -Wformat-security is enabled. + * + * \param p The number of the "format string" parameter. + * \param q The Number of the first variadic parameter. */ # define __printf(p,q) __attribute__ ((format (printf, p, q))) + /* * as direct use of __printf(p,q) confuses doxygen, here are two extra macros * for those values p,q that are actually used. */ + +/** First parameter is the format string, second the first variadic parameter. */ #define __printf_1_2 __printf(1,2) +/** Second parameter is the format string, third the first variadic parameter. */ #define __printf_2_3 __printf(2,3) +/** Print a warning if the return value is not used by the caller. */ # if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ > 3) # define __must_check __attribute__ ((warn_unused_result)) # else # define __must_check /* no warn_unused_result */ # endif + +/** + * A variant of static inline that requires the object being documented. + * + * If doxygen finds the \p static keyword in any context, that part will not be + * included in the documentation. However, we want static inline functions in + * header files to be documented while static functions in C files and + * statically declared variables should be left out. As a workaround for this + * flaw we use \p _static_inline_ for static inline functions declared in + * header files. + */ #define _static_inline_ static inline diff --git a/select.c b/select.c index d658585..4417880 100644 --- a/select.c +++ b/select.c @@ -942,7 +942,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) { diff --git a/string.c b/string.c index 17edffc..77c90cb 100644 --- a/string.c +++ b/string.c @@ -340,7 +340,7 @@ void free_argv(char **argv) * * In contrast to gengetopt's string parser, double quotes, backslash-escaped * characters and special characters like \p \\n are honored. The result - * contains pointers to copies of the words contained in \line and has to be + * contains pointers to copies of the words contained in \a line and has to be * freed by using \ref free_argv(). * * \param line The line to be split.