* - 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"
DEFINE_ERRLIST;
/**
- * The error code of the last osl library function.
+ * The error code of the last called osl library function.
*
* \sa osl().
*/
/** 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__)
* 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
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)
{
*
* 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.
projects / adu.git / commitdiff