httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s.@apache.org
Subject svn commit: r989377 - in /httpd/httpd/trunk/include: http_config.h http_log.h
Date Wed, 25 Aug 2010 21:29:41 GMT
Author: sf
Date: Wed Aug 25 21:29:41 2010
New Revision: 989377

URL: http://svn.apache.org/viewvc?rev=989377&view=rev
Log:
- add more comments explaining the logging macros
- make the documentation more doxygen friendly, as suggested by Justin
  Erenkrantz

Modified:
    httpd/httpd/trunk/include/http_config.h
    httpd/httpd/trunk/include/http_log.h

Modified: httpd/httpd/trunk/include/http_config.h
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/include/http_config.h?rev=989377&r1=989376&r2=989377&view=diff
==============================================================================
--- httpd/httpd/trunk/include/http_config.h (original)
+++ httpd/httpd/trunk/include/http_config.h Wed Aug 25 21:29:41 2010
@@ -395,13 +395,30 @@ struct module_struct {
     void (*register_hooks) (apr_pool_t *p);
 };
 
-/*
- * Macro to choose which module a file belongs to, for logging.
+/**
+ * The APLOG_USE_MODULE macro is used choose which module a file belongs to.
+ * This is necessary to allow per-module loglevel configuration.
+ *
+ * APLOG_USE_MODULE indirectly sets APLOG_MODULE_INDEX and APLOG_MARK.
+ *
+ * If a module should be backward compatible with versions before 2.3.6,
+ * APLOG_USE_MODULE needs to be enclosed in a #ifdef APLOG_USE_MODULE block.
+ *
+ * @param foo name of the module symbol of the current module, without the
+ *            trailing "_module" part
+ * @see APLOG_MARK
  */
 #define APLOG_USE_MODULE(foo) \
     extern module AP_MODULE_DECLARE_DATA foo##_module;                  \
     static int * const aplog_module_index = &(foo##_module.module_index)
 
+/**
+ * AP_DECLARE_MODULE is a convenience macro that combines a call of
+ * APLOG_USE_MODULE with the definition of the module symbol.
+ *
+ * If a module should be backward compatible with versions before 2.3.6,
+ * APLOG_USE_MODULE should be used explicitly instead of AP_DECLARE_MODULE.
+ */
 #define AP_DECLARE_MODULE(foo) \
     APLOG_USE_MODULE(foo);                         \
     module AP_MODULE_DECLARE_DATA foo##_module
@@ -520,7 +537,7 @@ AP_DECLARE(int) ap_get_request_module_lo
 /**
  * Accessor to set module-specific loglevel
  * @param p A pool
- * @param s The server for which to set the loglevel.
+ * @param l The ap_logconf struct to modify.
  * @param index The module_index of the module to set the loglevel for.
  * @param level The new log level
  */

Modified: httpd/httpd/trunk/include/http_log.h
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/include/http_log.h?rev=989377&r1=989376&r2=989377&view=diff
==============================================================================
--- httpd/httpd/trunk/include/http_log.h (original)
+++ httpd/httpd/trunk/include/http_log.h Wed Aug 25 21:29:41 2010
@@ -109,6 +109,15 @@ extern "C" {
 #define DEFAULT_LOGLEVEL	APLOG_WARNING
 #endif
 
+/**
+ * APLOG_NO_MODULE may be passed as module_index to ap_log_error() and related
+ * functions if the module causing the log message is not known. Normally this
+ * should not be used directly. Use APLOG_MARK or APLOG_MODULE_INDEX instead.
+ *
+ * @see APLOG_MARK
+ * @see APLOG_MODULE_INDEX
+ * @see ap_log_error
+ */
 #define APLOG_NO_MODULE         -1
 
 /*
@@ -116,15 +125,32 @@ extern "C" {
  * initialized explicitly. This means if aplog_module_index
  * is not initalized using the APLOG_USE_MODULE or the
  * AP_DECLARE_MODULE macro, we can safely fall back to
- * use APLOG_NO_MODULE.
+ * use APLOG_NO_MODULE. This variable will usually be optimized away.
  */
 static int * const aplog_module_index;
+
+/**
+ * APLOG_MODULE_INDEX contains the module_index of the current module if
+ * it has been set via the APLOG_USE_MODULE or AP_DECLARE_MODULE macro.
+ * Otherwise it contains APLOG_NO_MODULE (for example in unmodified httpd 2.2
+ * modules).
+ *
+ * If APLOG_MARK is used in ap_log_error() and related functions,
+ * APLOG_MODULE_INDEX will be passed as module_index. In cases where
+ * APLOG_MARK cannot be used, APLOG_MODULE_INDEX should normally be passed as
+ * module_index.
+ *
+ * @see APLOG_MARK
+ * @see ap_log_error
+ */
 #define APLOG_MODULE_INDEX  \
     (aplog_module_index ? *aplog_module_index : APLOG_NO_MODULE)
 
-/*
- * APLOG_MAX_LOGLEVEL can be used to remove logging above some
+/**
+ * APLOG_MAX_LOGLEVEL can be defined to remove logging above some
  * specified level at compile time.
+ *
+ * This requires a C99 compiler.
  */
 #ifndef APLOG_MAX_LOGLEVEL
 #define APLOG_MODULE_IS_LEVEL(s,module_index,level)              \
@@ -213,6 +239,21 @@ static int * const aplog_module_index;
 
 extern int AP_DECLARE_DATA ap_default_loglevel;
 
+/**
+ * APLOG_MARK is a convenience macro for use as the first three parameters in
+ * ap_log_error() and related functions, i.e. file, line, and module_index.
+ *
+ * The module_index parameter was introduced in version 2.3.6. Before that
+ * version, APLOG_MARK only replaced the file and line parameters.
+ * This means that APLOG_MARK can be used with ap_log_*error in all versions
+ * of Apache httpd.
+ *
+ * @see APLOG_MODULE_INDEX
+ * @see ap_log_error
+ * @see ap_log_cerror
+ * @see ap_log_rerror
+ * @see ap_log_cserror
+ */
 #define APLOG_MARK     __FILE__,__LINE__,APLOG_MODULE_INDEX
 
 /**
@@ -273,6 +314,7 @@ void ap_logs_child_init(apr_pool_t *p, s
  * @param s The server on which we are logging
  * @param fmt The format string
  * @param ... The arguments to use to fill out fmt.
+ * @note ap_log_error is implemented as a macro
  * @note Use APLOG_MARK to fill out file and line
  * @note If a request_rec is available, use that with ap_log_rerror()
  * in preference to calling this function.  Otherwise, if a conn_rec is
@@ -285,6 +327,11 @@ void ap_logs_child_init(apr_pool_t *p, s
  * simple format string like "%s", followed by the string containing the 
  * untrusted data.
  */
+#ifdef DOXYGEN
+AP_DECLARE(void) ap_log_error(const char *file, int line, int module_index,
+                              int level, apr_status_t status,
+                              const server_rec *s, const char *fmt, ...);
+#else
 #if __STDC_VERSION__ >= 199901L
 /* need additional step to expand APLOG_MARK first */
 #define ap_log_error(...) ap_log_error__(__VA_ARGS__)
@@ -300,6 +347,7 @@ AP_DECLARE(void) ap_log_error_(const cha
                                int level, apr_status_t status,
                                const server_rec *s, const char *fmt, ...)
                               __attribute__((format(printf,7,8)));
+#endif
 
 /**
  * ap_log_perror() - log messages which are not related to a particular
@@ -313,7 +361,8 @@ AP_DECLARE(void) ap_log_error_(const cha
  * @param p The pool which we are logging for
  * @param fmt The format string
  * @param ... The arguments to use to fill out fmt.
- * @note Use APLOG_MARK to fill out file and line
+ * @note ap_log_perror is implemented as a macro
+ * @note Use APLOG_MARK to fill out file, line, and module_index
  * @warning It is VERY IMPORTANT that you not include any raw data from 
  * the network, such as the request-URI or request header fields, within 
  * the format string.  Doing so makes the server vulnerable to a 
@@ -321,6 +370,11 @@ AP_DECLARE(void) ap_log_error_(const cha
  * simple format string like "%s", followed by the string containing the 
  * untrusted data.
  */
+#ifdef DOXYGEN
+AP_DECLARE(void) ap_log_perror(const char *file, int line, int module_index,
+                               int level, apr_status_t status, apr_pool_t *p,
+                               const char *fmt, ...);
+#else
 #if __STDC_VERSION__ >= 199901L && defined(APLOG_MAX_LOGLEVEL)
 /* need additional step to expand APLOG_MARK first */
 #define ap_log_perror(...) ap_log_perror__(__VA_ARGS__)
@@ -335,6 +389,7 @@ AP_DECLARE(void) ap_log_perror_(const ch
                                 int level, apr_status_t status, apr_pool_t *p,
                                 const char *fmt, ...)
                                __attribute__((format(printf,7,8)));
+#endif
 
 /**
  * ap_log_rerror() - log messages which are related to a particular
@@ -348,7 +403,8 @@ AP_DECLARE(void) ap_log_perror_(const ch
  * @param r The request which we are logging for
  * @param fmt The format string
  * @param ... The arguments to use to fill out fmt.
- * @note Use APLOG_MARK to fill out file and line
+ * @note ap_log_rerror is implemented as a macro
+ * @note Use APLOG_MARK to fill out file, line, and module_index
  * @warning It is VERY IMPORTANT that you not include any raw data from 
  * the network, such as the request-URI or request header fields, within 
  * the format string.  Doing so makes the server vulnerable to a 
@@ -356,6 +412,11 @@ AP_DECLARE(void) ap_log_perror_(const ch
  * simple format string like "%s", followed by the string containing the 
  * untrusted data.
  */
+#ifdef DOXYGEN
+AP_DECLARE(void) ap_log_rerror(const char *file, int line, int module_index,
+                               int level, apr_status_t status,
+                               const request_rec *r, const char *fmt, ...);
+#else
 #if __STDC_VERSION__ >= 199901L
 /* need additional step to expand APLOG_MARK first */
 #define ap_log_rerror(...) ap_log_rerror__(__VA_ARGS__)
@@ -369,7 +430,8 @@ AP_DECLARE(void) ap_log_perror_(const ch
 AP_DECLARE(void) ap_log_rerror_(const char *file, int line, int module_index,
                                 int level, apr_status_t status,
                                 const request_rec *r, const char *fmt, ...)
-			    __attribute__((format(printf,7,8)));
+                                __attribute__((format(printf,7,8)));
+#endif
 
 /**
  * ap_log_cerror() - log messages which are related to a particular
@@ -383,7 +445,8 @@ AP_DECLARE(void) ap_log_rerror_(const ch
  * @param c The connection which we are logging for
  * @param fmt The format string
  * @param ... The arguments to use to fill out fmt.
- * @note Use APLOG_MARK to fill out file and line
+ * @note ap_log_cerror is implemented as a macro
+ * @note Use APLOG_MARK to fill out file, line, and module_index
  * @note If a request_rec is available, use that with ap_log_rerror()
  * in preference to calling this function.
  * @warning It is VERY IMPORTANT that you not include any raw data from 
@@ -393,6 +456,11 @@ AP_DECLARE(void) ap_log_rerror_(const ch
  * simple format string like "%s", followed by the string containing the 
  * untrusted data.
  */
+#ifdef DOXYGEN
+AP_DECLARE(void) ap_log_cerror(const char *file, int line, int module_index,
+                               int level, apr_status_t status,
+                               const conn_rec *c, const char *fmt, ...);
+#else
 #if __STDC_VERSION__ >= 199901L
 /* need additional step to expand APLOG_MARK first */
 #define ap_log_cerror(...) ap_log_cerror__(__VA_ARGS__)
@@ -403,10 +471,11 @@ AP_DECLARE(void) ap_log_rerror_(const ch
 #else
 #define ap_log_cerror ap_log_cerror_
 #endif
-AP_DECLARE(void) ap_log_cerror_(const char *file, int line, int module_level,
+AP_DECLARE(void) ap_log_cerror_(const char *file, int line, int module_index,
                                 int level, apr_status_t status,
                                 const conn_rec *c, const char *fmt, ...)
-			    __attribute__((format(printf,7,8)));
+                                __attribute__((format(printf,7,8)));
+#endif
 
 /**
  * ap_log_cserror() - log messages which are related to a particular
@@ -421,7 +490,8 @@ AP_DECLARE(void) ap_log_cerror_(const ch
  * @param s The server which we are logging for
  * @param fmt The format string
  * @param ... The arguments to use to fill out fmt.
- * @note Use APLOG_MARK to fill out file and line
+ * @note ap_log_cserror is implemented as a macro
+ * @note Use APLOG_MARK to fill out file, line, and module_index
  * @note If a request_rec is available, use that with ap_log_rerror()
  * in preference to calling this function. This function is mainly useful for
  * modules like mod_ssl to use before the request_rec is created.
@@ -432,6 +502,12 @@ AP_DECLARE(void) ap_log_cerror_(const ch
  * simple format string like "%s", followed by the string containing the 
  * untrusted data.
  */
+#ifdef DOXYGEN
+AP_DECLARE(void) ap_log_cserror(const char *file, int line, int module_index,
+                                int level, apr_status_t status,
+                                const conn_rec *c, const server_rec *s,
+                                const char *fmt, ...);
+#else
 #if __STDC_VERSION__ >= 199901L
 /* need additional step to expand APLOG_MARK first */
 #define ap_log_cserror(...) ap_log_cserror__(__VA_ARGS__)
@@ -443,11 +519,12 @@ AP_DECLARE(void) ap_log_cerror_(const ch
 #else
 #define ap_log_cserror ap_log_cserror_
 #endif
-AP_DECLARE(void) ap_log_cserror_(const char *file, int line, int module_level,
+AP_DECLARE(void) ap_log_cserror_(const char *file, int line, int module_index,
                                  int level, apr_status_t status,
                                  const conn_rec *c, const server_rec *s,
                                  const char *fmt, ...)
                              __attribute__((format(printf,8,9)));
+#endif
 
 /**
  * Convert stderr to the error log



Mime
View raw message