granicus.if.org Git - apache/blob - include/http_log.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file  http_log.h
  19  * @brief Apache Logging library
  20  *
  21  * @defgroup APACHE_CORE_LOG Logging library
  22  * @ingroup  APACHE_CORE
  23  * @{
  24  */
  25
  26 #ifndef APACHE_HTTP_LOG_H
  27 #define APACHE_HTTP_LOG_H
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #include "apr_thread_proc.h"
  34 #include "http_config.h"
  35
  36 #ifdef HAVE_SYSLOG
  37 #include <syslog.h>
  38
  39 #ifndef LOG_PRIMASK
  40 #define LOG_PRIMASK 7
  41 #endif
  42
  43 #define APLOG_EMERG     LOG_EMERG       /* system is unusable */
  44 #define APLOG_ALERT     LOG_ALERT       /* action must be taken immediately */
  45 #define APLOG_CRIT      LOG_CRIT        /* critical conditions */
  46 #define APLOG_ERR       LOG_ERR         /* error conditions */
  47 #define APLOG_WARNING   LOG_WARNING     /* warning conditions */
  48 #define APLOG_NOTICE    LOG_NOTICE      /* normal but significant condition */
  49 #define APLOG_INFO      LOG_INFO        /* informational */
  50 #define APLOG_DEBUG     LOG_DEBUG       /* debug-level messages */
  51 #define APLOG_TRACE1   (LOG_DEBUG + 1)  /* trace-level 1 messages */
  52 #define APLOG_TRACE2   (LOG_DEBUG + 2)  /* trace-level 2 messages */
  53 #define APLOG_TRACE3   (LOG_DEBUG + 3)  /* trace-level 3 messages */
  54 #define APLOG_TRACE4   (LOG_DEBUG + 4)  /* trace-level 4 messages */
  55 #define APLOG_TRACE5   (LOG_DEBUG + 5)  /* trace-level 5 messages */
  56 #define APLOG_TRACE6   (LOG_DEBUG + 6)  /* trace-level 6 messages */
  57 #define APLOG_TRACE7   (LOG_DEBUG + 7)  /* trace-level 7 messages */
  58 #define APLOG_TRACE8   (LOG_DEBUG + 8)  /* trace-level 8 messages */
  59
  60 #define APLOG_LEVELMASK 15     /* mask off the level value */
  61
  62 #else
  63
  64 #define APLOG_EMERG      0     /* system is unusable */
  65 #define APLOG_ALERT      1     /* action must be taken immediately */
  66 #define APLOG_CRIT       2     /* critical conditions */
  67 #define APLOG_ERR        3     /* error conditions */
  68 #define APLOG_WARNING    4     /* warning conditions */
  69 #define APLOG_NOTICE     5     /* normal but significant condition */
  70 #define APLOG_INFO       6     /* informational */
  71 #define APLOG_DEBUG      7     /* debug-level messages */
  72 #define APLOG_TRACE1     8     /* trace-level 1 messages */
  73 #define APLOG_TRACE2     9     /* trace-level 2 messages */
  74 #define APLOG_TRACE3    10     /* trace-level 3 messages */
  75 #define APLOG_TRACE4    11     /* trace-level 4 messages */
  76 #define APLOG_TRACE5    12     /* trace-level 5 messages */
  77 #define APLOG_TRACE6    13     /* trace-level 6 messages */
  78 #define APLOG_TRACE7    14     /* trace-level 7 messages */
  79 #define APLOG_TRACE8    15     /* trace-level 8 messages */
  80
  81 #define APLOG_LEVELMASK 15     /* mask off the level value */
  82
  83 #endif
  84
  85 /* APLOG_NOERRNO is ignored and should not be used.  It will be
  86  * removed in a future release of Apache.
  87  */
  88 #define APLOG_NOERRNO           (APLOG_LEVELMASK + 1)
  89
  90 /** Use APLOG_TOCLIENT on ap_log_rerror() to give content
  91  * handlers the option of including the error text in the
  92  * ErrorDocument sent back to the client. Setting APLOG_TOCLIENT
  93  * will cause the error text to be saved in the request_rec->notes
  94  * table, keyed to the string "error-notes", if and only if:
  95  * - the severity level of the message is APLOG_WARNING or greater
  96  * - there are no other "error-notes" set in request_rec->notes
  97  * Once error-notes is set, it is up to the content handler to
  98  * determine whether this text should be sent back to the client.
  99  * Note: Client generated text streams sent back to the client MUST
 100  * be escaped to prevent CSS attacks.
 101  */
 102 #define APLOG_TOCLIENT          ((APLOG_LEVELMASK + 1) * 2)
 103
 104 /* normal but significant condition on startup, usually printed to stderr */
 105 #define APLOG_STARTUP           ((APLOG_LEVELMASK + 1) * 4)
 106
 107 #ifndef DEFAULT_LOGLEVEL
 108 #define DEFAULT_LOGLEVEL        APLOG_WARNING
 109 #endif
 110
 111 /**
 112  * APLOGNO() should be used at the start of the format string passed
 113  * to ap_log_error() and friends. The argument must be a 5 digit decimal
 114  * number. It creates a tag of the form "AH02182: "
 115  * See docs/log-message-tags/README for details.
 116  */
 117 #define APLOGNO(n)              "AH" #n ": "
 118
 119 /**
 120  * APLOG_NO_MODULE may be passed as module_index to ap_log_error() and related
 121  * functions if the module causing the log message is not known. Normally this
 122  * should not be used directly. Use ::APLOG_MARK or ::APLOG_MODULE_INDEX
 123  * instead.
 124  *
 125  * @see APLOG_MARK
 126  * @see APLOG_MODULE_INDEX
 127  * @see ap_log_error
 128  */
 129 #define APLOG_NO_MODULE         -1
 130
 131 #ifdef __cplusplus
 132 /**
 133  * C++ modules must invoke ::APLOG_USE_MODULE or ::AP_DECLARE_MODULE in
 134  * every file which uses ap_log_* before the first use of ::APLOG_MARK
 135  * or ::APLOG_MODULE_INDEX.
 136  * (C modules *should* do that as well, to enable module-specific log
 137  * levels. C modules need not obey the ordering, though).
 138  */
 139 #else /* __cplusplus */
 140 /**
 141  * Constant to store module_index for the current file.
 142  * Objects with static storage duration are set to NULL if not
 143  * initialized explicitly. This means that if aplog_module_index
 144  * is not initalized using the ::APLOG_USE_MODULE or the
 145  * ::AP_DECLARE_MODULE macro, we can safely fall back to
 146  * use ::APLOG_NO_MODULE. This variable will usually be optimized away.
 147  */
 148 static int * const aplog_module_index;
 149 #endif /* __cplusplus */
 150
 151 /**
 152  * APLOG_MODULE_INDEX contains the module_index of the current module if
 153  * it has been set via the ::APLOG_USE_MODULE or ::AP_DECLARE_MODULE macro.
 154  * Otherwise it contains ::APLOG_NO_MODULE (for example in unmodified httpd
 155  * 2.2 modules).
 156  *
 157  * If ::APLOG_MARK is used in ap_log_error() and related functions,
 158  * ::APLOG_MODULE_INDEX will be passed as module_index. In cases where
 159  * ::APLOG_MARK cannot be used, ::APLOG_MODULE_INDEX should normally be passed
 160  * as module_index.
 161  *
 162  * @see APLOG_MARK
 163  * @see ap_log_error
 164  */
 165 #ifdef __cplusplus
 166 #define APLOG_MODULE_INDEX (*aplog_module_index)
 167 #else /* __cplusplus */
 168 #define APLOG_MODULE_INDEX  \
 169     (aplog_module_index ? *aplog_module_index : APLOG_NO_MODULE)
 170 #endif /* __cplusplus */
 171
 172 /**
 173  * APLOG_MAX_LOGLEVEL can be defined to remove logging above some
 174  * specified level at compile time.
 175  *
 176  * This requires a C99 compiler.
 177  */
 178 #ifdef DOXYGEN
 179 #define APLOG_MAX_LOGLEVEL
 180 #endif
 181 #ifndef APLOG_MAX_LOGLEVEL
 182 #define APLOG_MODULE_IS_LEVEL(s,module_index,level)              \
 183           ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) ||       \
 184             (s == NULL) ||                                       \
 185             (ap_get_server_module_loglevel(s, module_index)      \
 186              >= ((level)&APLOG_LEVELMASK) ) )
 187 #define APLOG_C_MODULE_IS_LEVEL(c,module_index,level)            \
 188           ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) ||       \
 189             (ap_get_conn_module_loglevel(c, module_index)        \
 190              >= ((level)&APLOG_LEVELMASK) ) )
 191 #define APLOG_CS_MODULE_IS_LEVEL(c,s,module_index,level)            \
 192           ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) ||          \
 193             (ap_get_conn_server_module_loglevel(c, s, module_index) \
 194              >= ((level)&APLOG_LEVELMASK) ) )
 195 #define APLOG_R_MODULE_IS_LEVEL(r,module_index,level)            \
 196           ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) ||       \
 197             (ap_get_request_module_loglevel(r, module_index)     \
 198              >= ((level)&APLOG_LEVELMASK) ) )
 199 #else
 200 #define APLOG_MODULE_IS_LEVEL(s,module_index,level)              \
 201         ( (((level)&APLOG_LEVELMASK) <= APLOG_MAX_LOGLEVEL) &&   \
 202           ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) ||       \
 203             (s == NULL) ||                                       \
 204             (ap_get_server_module_loglevel(s, module_index)      \
 205              >= ((level)&APLOG_LEVELMASK) ) ) )
 206 #define APLOG_CS_MODULE_IS_LEVEL(c,s,module_index,level)            \
 207         ( (((level)&APLOG_LEVELMASK) <= APLOG_MAX_LOGLEVEL) &&      \
 208           ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) ||          \
 209             (ap_get_conn_server_module_loglevel(c, s, module_index) \
 210              >= ((level)&APLOG_LEVELMASK) ) ) )
 211 #define APLOG_C_MODULE_IS_LEVEL(c,module_index,level)            \
 212         ( (((level)&APLOG_LEVELMASK) <= APLOG_MAX_LOGLEVEL) &&   \
 213           ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) ||       \
 214             (ap_get_conn_module_loglevel(c, module_index)        \
 215              >= ((level)&APLOG_LEVELMASK) ) ) )
 216 #define APLOG_R_MODULE_IS_LEVEL(r,module_index,level)            \
 217         ( (((level)&APLOG_LEVELMASK) <= APLOG_MAX_LOGLEVEL) &&   \
 218           ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) ||       \
 219             (ap_get_request_module_loglevel(r, module_index)     \
 220              >= ((level)&APLOG_LEVELMASK) ) ) )
 221 #endif
 222
 223 #define APLOG_IS_LEVEL(s,level)     \
 224     APLOG_MODULE_IS_LEVEL(s,APLOG_MODULE_INDEX,level)
 225 #define APLOG_C_IS_LEVEL(c,level)   \
 226     APLOG_C_MODULE_IS_LEVEL(c,APLOG_MODULE_INDEX,level)
 227 #define APLOG_CS_IS_LEVEL(c,s,level) \
 228     APLOG_CS_MODULE_IS_LEVEL(c,s,APLOG_MODULE_INDEX,level)
 229 #define APLOG_R_IS_LEVEL(r,level)   \
 230     APLOG_R_MODULE_IS_LEVEL(r,APLOG_MODULE_INDEX,level)
 231
 232
 233 #define APLOGinfo(s)                APLOG_IS_LEVEL(s,APLOG_INFO)
 234 #define APLOGdebug(s)               APLOG_IS_LEVEL(s,APLOG_DEBUG)
 235 #define APLOGtrace1(s)              APLOG_IS_LEVEL(s,APLOG_TRACE1)
 236 #define APLOGtrace2(s)              APLOG_IS_LEVEL(s,APLOG_TRACE2)
 237 #define APLOGtrace3(s)              APLOG_IS_LEVEL(s,APLOG_TRACE3)
 238 #define APLOGtrace4(s)              APLOG_IS_LEVEL(s,APLOG_TRACE4)
 239 #define APLOGtrace5(s)              APLOG_IS_LEVEL(s,APLOG_TRACE5)
 240 #define APLOGtrace6(s)              APLOG_IS_LEVEL(s,APLOG_TRACE6)
 241 #define APLOGtrace7(s)              APLOG_IS_LEVEL(s,APLOG_TRACE7)
 242 #define APLOGtrace8(s)              APLOG_IS_LEVEL(s,APLOG_TRACE8)
 243
 244 #define APLOGrinfo(r)               APLOG_R_IS_LEVEL(r,APLOG_INFO)
 245 #define APLOGrdebug(r)              APLOG_R_IS_LEVEL(r,APLOG_DEBUG)
 246 #define APLOGrtrace1(r)             APLOG_R_IS_LEVEL(r,APLOG_TRACE1)
 247 #define APLOGrtrace2(r)             APLOG_R_IS_LEVEL(r,APLOG_TRACE2)
 248 #define APLOGrtrace3(r)             APLOG_R_IS_LEVEL(r,APLOG_TRACE3)
 249 #define APLOGrtrace4(r)             APLOG_R_IS_LEVEL(r,APLOG_TRACE4)
 250 #define APLOGrtrace5(r)             APLOG_R_IS_LEVEL(r,APLOG_TRACE5)
 251 #define APLOGrtrace6(r)             APLOG_R_IS_LEVEL(r,APLOG_TRACE6)
 252 #define APLOGrtrace7(r)             APLOG_R_IS_LEVEL(r,APLOG_TRACE7)
 253 #define APLOGrtrace8(r)             APLOG_R_IS_LEVEL(r,APLOG_TRACE8)
 254
 255 #define APLOGcinfo(c)               APLOG_C_IS_LEVEL(c,APLOG_INFO)
 256 #define APLOGcdebug(c)              APLOG_C_IS_LEVEL(c,APLOG_DEBUG)
 257 #define APLOGctrace1(c)             APLOG_C_IS_LEVEL(c,APLOG_TRACE1)
 258 #define APLOGctrace2(c)             APLOG_C_IS_LEVEL(c,APLOG_TRACE2)
 259 #define APLOGctrace3(c)             APLOG_C_IS_LEVEL(c,APLOG_TRACE3)
 260 #define APLOGctrace4(c)             APLOG_C_IS_LEVEL(c,APLOG_TRACE4)
 261 #define APLOGctrace5(c)             APLOG_C_IS_LEVEL(c,APLOG_TRACE5)
 262 #define APLOGctrace6(c)             APLOG_C_IS_LEVEL(c,APLOG_TRACE6)
 263 #define APLOGctrace7(c)             APLOG_C_IS_LEVEL(c,APLOG_TRACE7)
 264 #define APLOGctrace8(c)             APLOG_C_IS_LEVEL(c,APLOG_TRACE8)
 265
 266 AP_DECLARE_DATA extern int ap_default_loglevel;
 267
 268 /**
 269  * APLOG_MARK is a convenience macro for use as the first three parameters in
 270  * ap_log_error() and related functions, i.e. file, line, and module_index.
 271  *
 272  * The module_index parameter was introduced in version 2.3.6. Before that
 273  * version, APLOG_MARK only replaced the file and line parameters.
 274  * This means that APLOG_MARK can be used with ap_log_*error in all versions
 275  * of Apache httpd.
 276  *
 277  * @see APLOG_MODULE_INDEX
 278  * @see ap_log_error
 279  * @see ap_log_cerror
 280  * @see ap_log_rerror
 281  * @see ap_log_cserror
 282  */
 283 #define APLOG_MARK     __FILE__,__LINE__,APLOG_MODULE_INDEX
 284
 285 /**
 286  * Set up for logging to stderr.
 287  * @param p The pool to allocate out of
 288  */
 289 AP_DECLARE(void) ap_open_stderr_log(apr_pool_t *p);
 290
 291 /**
 292  * Replace logging to stderr with logging to the given file.
 293  * @param p The pool to allocate out of
 294  * @param file Name of the file to log stderr output
 295  */
 296 AP_DECLARE(apr_status_t) ap_replace_stderr_log(apr_pool_t *p,
 297                                                const char *file);
 298
 299 /**
 300  * Open the error log and replace stderr with it.
 301  * @param pconf Not used
 302  * @param plog  The pool to allocate the logs from
 303  * @param ptemp Pool used for temporary allocations
 304  * @param s_main The main server
 305  * @note ap_open_logs isn't expected to be used by modules, it is
 306  * an internal core function
 307  */
 308 int ap_open_logs(apr_pool_t *pconf, apr_pool_t *plog,
 309                  apr_pool_t *ptemp, server_rec *s_main);
 310
 311 /**
 312  * Perform special processing for piped loggers in MPM child
 313  * processes.
 314  * @param p Not used
 315  * @param s Not used
 316  * @note ap_logs_child_init is not for use by modules; it is an
 317  * internal core function
 318  */
 319 void ap_logs_child_init(apr_pool_t *p, server_rec *s);
 320
 321 /*
 322  * The primary logging functions, ap_log_error, ap_log_rerror, ap_log_cerror,
 323  * and ap_log_perror use a printf style format string to build the log message.
 324  * It is VERY IMPORTANT that you not include any raw data from the network,
 325  * such as the request-URI or request header fields, within the format
 326  * string.  Doing so makes the server vulnerable to a denial-of-service
 327  * attack and other messy behavior.  Instead, use a simple format string
 328  * like "%s", followed by the string containing the untrusted data.
 329  */
 330
 331 /**
 332  * ap_log_error() - log messages which are not related to a particular
 333  * request or connection.  This uses a printf-like format to log messages
 334  * to the error_log.
 335  * @param file The file in which this function is called
 336  * @param line The line number on which this function is called
 337  * @param module_index The module_index of the module generating this message
 338  * @param level The level of this error message
 339  * @param status The status code from the previous command
 340  * @param s The server on which we are logging
 341  * @param fmt The format string
 342  * @param ... The arguments to use to fill out fmt.
 343  * @note ap_log_error is implemented as a macro
 344  * @note Use APLOG_MARK to fill out file and line
 345  * @note If a request_rec is available, use that with ap_log_rerror()
 346  * in preference to calling this function.  Otherwise, if a conn_rec is
 347  * available, use that with ap_log_cerror() in preference to calling
 348  * this function.
 349  * @warning It is VERY IMPORTANT that you not include any raw data from
 350  * the network, such as the request-URI or request header fields, within
 351  * the format string.  Doing so makes the server vulnerable to a
 352  * denial-of-service attack and other messy behavior.  Instead, use a
 353  * simple format string like "%s", followed by the string containing the
 354  * untrusted data.
 355  */
 356 #ifdef DOXYGEN
 357 AP_DECLARE(void) ap_log_error(const char *file, int line, int module_index,
 358                               int level, apr_status_t status,
 359                               const server_rec *s, const char *fmt, ...);
 360 #else
 361 #ifdef AP_HAVE_C99
 362 /* need additional step to expand APLOG_MARK first */
 363 #define ap_log_error(...) ap_log_error__(__VA_ARGS__)
 364 /* need server_rec *sr = ... for the case if s is verbatim NULL */
 365 #define ap_log_error__(file, line, mi, level, status, s, ...)           \
 366     do { const server_rec *sr__ = s; if (APLOG_MODULE_IS_LEVEL(sr__, mi, level)) \
 367              ap_log_error_(file, line, mi, level, status, sr__, __VA_ARGS__);    \
 368     } while(0)
 369 #else
 370 #define ap_log_error ap_log_error_
 371 #endif
 372 AP_DECLARE(void) ap_log_error_(const char *file, int line, int module_index,
 373                                int level, apr_status_t status,
 374                                const server_rec *s, const char *fmt, ...)
 375                               __attribute__((format(printf,7,8)));
 376 #endif
 377
 378 /**
 379  * ap_log_perror() - log messages which are not related to a particular
 380  * request, connection, or virtual server.  This uses a printf-like
 381  * format to log messages to the error_log.
 382  * @param file The file in which this function is called
 383  * @param line The line number on which this function is called
 384  * @param module_index ignored dummy value for use by APLOG_MARK
 385  * @param level The level of this error message
 386  * @param status The status code from the previous command
 387  * @param p The pool which we are logging for
 388  * @param fmt The format string
 389  * @param ... The arguments to use to fill out fmt.
 390  * @note ap_log_perror is implemented as a macro
 391  * @note Use APLOG_MARK to fill out file, line, and module_index
 392  * @warning It is VERY IMPORTANT that you not include any raw data from
 393  * the network, such as the request-URI or request header fields, within
 394  * the format string.  Doing so makes the server vulnerable to a
 395  * denial-of-service attack and other messy behavior.  Instead, use a
 396  * simple format string like "%s", followed by the string containing the
 397  * untrusted data.
 398  */
 399 #ifdef DOXYGEN
 400 AP_DECLARE(void) ap_log_perror(const char *file, int line, int module_index,
 401                                int level, apr_status_t status, apr_pool_t *p,
 402                                const char *fmt, ...);
 403 #else
 404 #if defined(AP_HAVE_C99) && defined(APLOG_MAX_LOGLEVEL)
 405 /* need additional step to expand APLOG_MARK first */
 406 #define ap_log_perror(...) ap_log_perror__(__VA_ARGS__)
 407 #define ap_log_perror__(file, line, mi, level, status, p, ...)            \
 408     do { if ((level) <= APLOG_MAX_LOGLEVEL )                              \
 409              ap_log_perror_(file, line, mi, level, status, p,             \
 410                             __VA_ARGS__); } while(0)
 411 #else
 412 #define ap_log_perror ap_log_perror_
 413 #endif
 414 AP_DECLARE(void) ap_log_perror_(const char *file, int line, int module_index,
 415                                 int level, apr_status_t status, apr_pool_t *p,
 416                                 const char *fmt, ...)
 417                                __attribute__((format(printf,7,8)));
 418 #endif
 419
 420 /**
 421  * ap_log_rerror() - log messages which are related to a particular
 422  * request.  This uses a printf-like format to log messages to the
 423  * error_log.
 424  * @param file The file in which this function is called
 425  * @param line The line number on which this function is called
 426  * @param module_index The module_index of the module generating this message
 427  * @param level The level of this error message
 428  * @param status The status code from the previous command
 429  * @param r The request which we are logging for
 430  * @param fmt The format string
 431  * @param ... The arguments to use to fill out fmt.
 432  * @note ap_log_rerror is implemented as a macro
 433  * @note Use APLOG_MARK to fill out file, line, and module_index
 434  * @warning It is VERY IMPORTANT that you not include any raw data from
 435  * the network, such as the request-URI or request header fields, within
 436  * the format string.  Doing so makes the server vulnerable to a
 437  * denial-of-service attack and other messy behavior.  Instead, use a
 438  * simple format string like "%s", followed by the string containing the
 439  * untrusted data.
 440  */
 441 #ifdef DOXYGEN
 442 AP_DECLARE(void) ap_log_rerror(const char *file, int line, int module_index,
 443                                int level, apr_status_t status,
 444                                const request_rec *r, const char *fmt, ...);
 445 #else
 446 #ifdef AP_HAVE_C99
 447 /* need additional step to expand APLOG_MARK first */
 448 #define ap_log_rerror(...) ap_log_rerror__(__VA_ARGS__)
 449 #define ap_log_rerror__(file, line, mi, level, status, r, ...)              \
 450     do { if (APLOG_R_MODULE_IS_LEVEL(r, mi, level))                         \
 451              ap_log_rerror_(file, line, mi, level, status, r, __VA_ARGS__); \
 452     } while(0)
 453 #else
 454 #define ap_log_rerror ap_log_rerror_
 455 #endif
 456 AP_DECLARE(void) ap_log_rerror_(const char *file, int line, int module_index,
 457                                 int level, apr_status_t status,
 458                                 const request_rec *r, const char *fmt, ...)
 459                                 __attribute__((format(printf,7,8)));
 460 #endif
 461
 462 /**
 463  * ap_log_cerror() - log messages which are related to a particular
 464  * connection.  This uses a printf-like format to log messages to the
 465  * error_log.
 466  * @param file The file in which this function is called
 467  * @param line The line number on which this function is called
 468  * @param level The level of this error message
 469  * @param module_index The module_index of the module generating this message
 470  * @param status The status code from the previous command
 471  * @param c The connection which we are logging for
 472  * @param fmt The format string
 473  * @param ... The arguments to use to fill out fmt.
 474  * @note ap_log_cerror is implemented as a macro
 475  * @note Use APLOG_MARK to fill out file, line, and module_index
 476  * @note If a request_rec is available, use that with ap_log_rerror()
 477  * in preference to calling this function.
 478  * @warning It is VERY IMPORTANT that you not include any raw data from
 479  * the network, such as the request-URI or request header fields, within
 480  * the format string.  Doing so makes the server vulnerable to a
 481  * denial-of-service attack and other messy behavior.  Instead, use a
 482  * simple format string like "%s", followed by the string containing the
 483  * untrusted data.
 484  */
 485 #ifdef DOXYGEN
 486 AP_DECLARE(void) ap_log_cerror(const char *file, int line, int module_index,
 487                                int level, apr_status_t status,
 488                                const conn_rec *c, const char *fmt, ...);
 489 #else
 490 #ifdef AP_HAVE_C99
 491 /* need additional step to expand APLOG_MARK first */
 492 #define ap_log_cerror(...) ap_log_cerror__(__VA_ARGS__)
 493 #define ap_log_cerror__(file, line, mi, level, status, c, ...)              \
 494     do { if (APLOG_C_MODULE_IS_LEVEL(c, mi, level))                         \
 495              ap_log_cerror_(file, line, mi, level, status, c, __VA_ARGS__); \
 496     } while(0)
 497 #else
 498 #define ap_log_cerror ap_log_cerror_
 499 #endif
 500 AP_DECLARE(void) ap_log_cerror_(const char *file, int line, int module_index,
 501                                 int level, apr_status_t status,
 502                                 const conn_rec *c, const char *fmt, ...)
 503                                 __attribute__((format(printf,7,8)));
 504 #endif
 505
 506 /**
 507  * ap_log_cserror() - log messages which are related to a particular
 508  * connection and to a vhost other than c->base_server.  This uses a
 509  * printf-like format to log messages to the error_log.
 510  * @param file The file in which this function is called
 511  * @param line The line number on which this function is called
 512  * @param level The level of this error message
 513  * @param module_index The module_index of the module generating this message
 514  * @param status The status code from the previous command
 515  * @param c The connection which we are logging for
 516  * @param s The server which we are logging for
 517  * @param fmt The format string
 518  * @param ... The arguments to use to fill out fmt.
 519  * @note ap_log_cserror is implemented as a macro
 520  * @note Use APLOG_MARK to fill out file, line, and module_index
 521  * @note If a request_rec is available, use that with ap_log_rerror()
 522  * in preference to calling this function. This function is mainly useful for
 523  * modules like mod_ssl to use before the request_rec is created.
 524  * @warning It is VERY IMPORTANT that you not include any raw data from
 525  * the network, such as the request-URI or request header fields, within
 526  * the format string.  Doing so makes the server vulnerable to a
 527  * denial-of-service attack and other messy behavior.  Instead, use a
 528  * simple format string like "%s", followed by the string containing the
 529  * untrusted data.
 530  */
 531 #ifdef DOXYGEN
 532 AP_DECLARE(void) ap_log_cserror(const char *file, int line, int module_index,
 533                                 int level, apr_status_t status,
 534                                 const conn_rec *c, const server_rec *s,
 535                                 const char *fmt, ...);
 536 #else
 537 #ifdef AP_HAVE_C99
 538 /* need additional step to expand APLOG_MARK first */
 539 #define ap_log_cserror(...) ap_log_cserror__(__VA_ARGS__)
 540 #define ap_log_cserror__(file, line, mi, level, status, c, s, ...)  \
 541     do { if (APLOG_CS_MODULE_IS_LEVEL(c, s, mi, level))             \
 542              ap_log_cserror_(file, line, mi, level, status, c, s,   \
 543                              __VA_ARGS__);                          \
 544     } while(0)
 545 #else
 546 #define ap_log_cserror ap_log_cserror_
 547 #endif
 548 AP_DECLARE(void) ap_log_cserror_(const char *file, int line, int module_index,
 549                                  int level, apr_status_t status,
 550                                  const conn_rec *c, const server_rec *s,
 551                                  const char *fmt, ...)
 552                              __attribute__((format(printf,8,9)));
 553 #endif
 554
 555 /*
 556  * The buffer logging functions, ap_log_data, ap_log_rdata, ap_log_cdata,
 557  * and ap_log_csdata log a buffer in printable and hex format.  The exact
 558  * format is controlled by processing flags, described next.
 559  */
 560
 561 /**
 562  * Processing flags for ap_log_data() et al
 563  *
 564  * AP_LOG_DATA_DEFAULT - default formatting, with printable chars and hex
 565  * AP_LOG_DATA_SHOW_OFFSET - prefix each line with hex offset from the start
 566  * of the buffer
 567  */
 568 #define AP_LOG_DATA_DEFAULT       0
 569 #define AP_LOG_DATA_SHOW_OFFSET   1
 570
 571 /**
 572  * ap_log_data() - log buffers which are not related to a particular request
 573  * or connection.
 574  * @param file The file in which this function is called
 575  * @param line The line number on which this function is called
 576  * @param module_index The module_index of the module logging this buffer
 577  * @param level The log level
 578  * @param s The server on which we are logging
 579  * @param label A label for the buffer, to be logged preceding the buffer
 580  * @param data The buffer to be logged
 581  * @param len The length of the buffer
 582  * @param flags Special processing flags like AP_LOG_DATA_SHOW_OFFSET
 583  * @note ap_log_data is implemented as a macro.
 584  * @note Use APLOG_MARK to fill out file, line, and module_index
 585  * @note If a request_rec is available, use that with ap_log_rdata()
 586  * in preference to calling this function.  Otherwise, if a conn_rec is
 587  * available, use that with ap_log_cdata() in preference to calling
 588  * this function.
 589  */
 590 #ifdef DOXYGEN
 591 AP_DECLARE(void) ap_log_data(const char *file, int line, int module_index,
 592                              int level, const server_rec *s, const char *label,
 593                              const void *data, apr_size_t len, unsigned int flags);
 594 #else
 595 #ifdef AP_HAVE_C99
 596 /* need additional step to expand APLOG_MARK first */
 597 #define ap_log_data(...) ap_log_data__(__VA_ARGS__)
 598 /* need server_rec *sr = ... for the case if s is verbatim NULL */
 599 #define ap_log_data__(file, line, mi, level, s, ...)           \
 600     do { const server_rec *sr__ = s; if (APLOG_MODULE_IS_LEVEL(sr__, mi, level)) \
 601              ap_log_data_(file, line, mi, level, sr__, __VA_ARGS__);    \
 602     } while(0)
 603 #else
 604 #define ap_log_data ap_log_data_
 605 #endif
 606 AP_DECLARE(void) ap_log_data_(const char *file, int line, int module_index,
 607                               int level, const server_rec *s, const char *label,
 608                               const void *data, apr_size_t len, unsigned int flags);
 609 #endif
 610
 611 /**
 612  * ap_log_rdata() - log buffers which are related to a particular request.
 613  * @param file The file in which this function is called
 614  * @param line The line number on which this function is called
 615  * @param module_index The module_index of the module logging this buffer
 616  * @param level The log level
 617  * @param r The request which we are logging for
 618  * @param label A label for the buffer, to be logged preceding the buffer
 619  * @param data The buffer to be logged
 620  * @param len The length of the buffer
 621  * @param flags Special processing flags like AP_LOG_DATA_SHOW_OFFSET
 622  * @note ap_log_rdata is implemented as a macro.
 623  * @note Use APLOG_MARK to fill out file, line, and module_index
 624  * @note If a request_rec is available, use that with ap_log_rerror()
 625  * in preference to calling this function.  Otherwise, if a conn_rec is
 626  * available, use that with ap_log_cerror() in preference to calling
 627  * this function.
 628  */
 629 #ifdef DOXYGEN
 630 AP_DECLARE(void) ap_log_rdata(const char *file, int line, int module_index,
 631                               int level, const request_rec *r, const char *label,
 632                               const void *data, apr_size_t len, unsigned int flags);
 633 #else
 634 #ifdef AP_HAVE_C99
 635 /* need additional step to expand APLOG_MARK first */
 636 #define ap_log_rdata(...) ap_log_rdata__(__VA_ARGS__)
 637 #define ap_log_rdata__(file, line, mi, level, s, ...)           \
 638     do { if (APLOG_R_MODULE_IS_LEVEL(r, mi, level)) \
 639              ap_log_rdata_(file, line, mi, level, r, __VA_ARGS__);    \
 640     } while(0)
 641 #else
 642 #define ap_log_rdata ap_log_rdata_
 643 #endif
 644 AP_DECLARE(void) ap_log_rdata_(const char *file, int line, int module_index,
 645                                int level, const request_rec *r, const char *label,
 646                                const void *data, apr_size_t len, unsigned int flags);
 647 #endif
 648
 649 /**
 650  * ap_log_cdata() - log buffers which are related to a particular connection.
 651  * @param file The file in which this function is called
 652  * @param line The line number on which this function is called
 653  * @param module_index The module_index of the module logging this buffer
 654  * @param level The log level
 655  * @param c The connection which we are logging for
 656  * @param label A label for the buffer, to be logged preceding the buffer
 657  * @param data The buffer to be logged
 658  * @param len The length of the buffer
 659  * @param flags Special processing flags like AP_LOG_DATA_SHOW_OFFSET
 660  * @note ap_log_cdata is implemented as a macro
 661  * @note Use APLOG_MARK to fill out file, line, and module_index
 662  * @note If a request_rec is available, use that with ap_log_rerror()
 663  * in preference to calling this function.  Otherwise, if a conn_rec is
 664  * available, use that with ap_log_cerror() in preference to calling
 665  * this function.
 666  */
 667 #ifdef DOXYGEN
 668 AP_DECLARE(void) ap_log_cdata(const char *file, int line, int module_index,
 669                               int level, const conn_rec *c, const char *label,
 670                               const void *data, apr_size_t len, unsigned int flags);
 671 #else
 672 #ifdef AP_HAVE_C99
 673 /* need additional step to expand APLOG_MARK first */
 674 #define ap_log_cdata(...) ap_log_cdata__(__VA_ARGS__)
 675 #define ap_log_cdata__(file, line, mi, level, c, ...)           \
 676     do { if (APLOG_C_MODULE_IS_LEVEL(c, mi, level)) \
 677              ap_log_cdata_(file, line, mi, level, c, __VA_ARGS__);    \
 678     } while(0)
 679 #else
 680 #define ap_log_cdata ap_log_cdata_
 681 #endif
 682 AP_DECLARE(void) ap_log_cdata_(const char *file, int line, int module_index,
 683                                int level, const conn_rec *c, const char *label,
 684                                const void *data, apr_size_t len, unsigned int flags);
 685 #endif
 686
 687 /**
 688  * ap_log_csdata() - log buffers which are related to a particular connection
 689  * and to a vhost other than c->base_server.
 690  * @param file The file in which this function is called
 691  * @param line The line number on which this function is called
 692  * @param module_index The module_index of the module logging this buffer
 693  * @param level The log level
 694  * @param c The connection which we are logging for
 695  * @param s The server which we are logging for
 696  * @param label A label for the buffer, to be logged preceding the buffer
 697  * @param data The buffer to be logged
 698  * @param len The length of the buffer
 699  * @param flags Special processing flags like AP_LOG_DATA_SHOW_OFFSET
 700  * @note ap_log_csdata is implemented as a macro
 701  * @note Use APLOG_MARK to fill out file, line, and module_index
 702  * @note If a request_rec is available, use that with ap_log_rerror()
 703  * in preference to calling this function.  Otherwise, if a conn_rec is
 704  * available, use that with ap_log_cerror() in preference to calling
 705  * this function.
 706  */
 707 #ifdef DOXYGEN
 708 AP_DECLARE(void) ap_log_csdata(const char *file, int line, int module_index,
 709                                int level, const conn_rec *c, const server_rec *s,
 710                                const char *label, const void *data,
 711                                apr_size_t len, unsigned int flags);
 712 #else
 713 #ifdef AP_HAVE_C99
 714 /* need additional step to expand APLOG_MARK first */
 715 #define ap_log_csdata(...) ap_log_csdata__(__VA_ARGS__)
 716 #define ap_log_csdata__(file, line, mi, level, c, s, ...)              \
 717     do { if (APLOG_CS_MODULE_IS_LEVEL(c, s, mi, level))                \
 718              ap_log_csdata_(file, line, mi, level, c, s, __VA_ARGS__); \
 719     } while(0)
 720 #else
 721 #define ap_log_cdata ap_log_cdata_
 722 #endif
 723 AP_DECLARE(void) ap_log_csdata_(const char *file, int line, int module_index,
 724                                 int level, const conn_rec *c, const server_rec *s,
 725                                 const char *label, const void *data,
 726                                 apr_size_t len, unsigned int flags);
 727 #endif
 728
 729 /**
 730  * Convert stderr to the error log
 731  * @param s The current server
 732  */
 733 AP_DECLARE(void) ap_error_log2stderr(server_rec *s);
 734
 735 /**
 736  * Log the command line used to start the server.
 737  * @param p The pool to use for logging
 738  * @param s The server_rec whose process's command line we want to log.
 739  * The command line is logged to that server's error log.
 740  */
 741 AP_DECLARE(void) ap_log_command_line(apr_pool_t *p, server_rec *s);
 742
 743 /**
 744  * Log common shared data
 745  * @param s The server_rec whose process's command line we want to log.
 746  * Misc commonly logged data is logged to that server's error log.
 747  */
 748 AP_DECLARE(void) ap_log_common(server_rec *s);
 749
 750 /**
 751  * Log the current pid of the parent process
 752  * @param p The pool to use for processing
 753  * @param fname The name of the file to log to.  If the filename is not
 754  * absolute then it is assumed to be relative to DefaultRuntimeDir.
 755  */
 756 AP_DECLARE(void) ap_log_pid(apr_pool_t *p, const char *fname);
 757
 758 /**
 759  * Remove the pidfile.
 760  * @param p The pool to use for processing
 761  * @param fname The name of the pid file to remove.  If the filename is not
 762  * absolute then it is assumed to be relative to DefaultRuntimeDir.
 763  */
 764 AP_DECLARE(void) ap_remove_pid(apr_pool_t *p, const char *fname);
 765
 766 /**
 767  * Retrieve the pid from a pidfile.
 768  * @param p The pool to use for processing
 769  * @param filename The name of the file containing the pid.  If the filename
 770  * is not absolute then it is assumed to be relative to DefaultRuntimeDir.
 771  * @param mypid Pointer to pid_t (valid only if return APR_SUCCESS)
 772  */
 773 AP_DECLARE(apr_status_t) ap_read_pid(apr_pool_t *p, const char *filename, pid_t *mypid);
 774
 775 /** @see piped_log */
 776 typedef struct piped_log piped_log;
 777
 778 /**
 779  * Open the piped log process
 780  * @param p The pool to allocate out of
 781  * @param program The program to run in the logging process
 782  * @return The piped log structure
 783  * @note The log program is invoked as @p APR_PROGRAM_ENV,
 784  *      @see ap_open_piped_log_ex to modify this behavior
 785  */
 786 AP_DECLARE(piped_log *) ap_open_piped_log(apr_pool_t *p, const char *program);
 787
 788 /**
 789  * Open the piped log process specifying the execution choice for program
 790  * @param p The pool to allocate out of
 791  * @param program The program to run in the logging process
 792  * @param cmdtype How to invoke program, e.g. APR_PROGRAM, APR_SHELLCMD_ENV, etc
 793  * @return The piped log structure
 794  */
 795 AP_DECLARE(piped_log *) ap_open_piped_log_ex(apr_pool_t *p,
 796                                              const char *program,
 797                                              apr_cmdtype_e cmdtype);
 798
 799 /**
 800  * Close the piped log and kill the logging process
 801  * @param pl The piped log structure
 802  */
 803 AP_DECLARE(void) ap_close_piped_log(piped_log *pl);
 804
 805 /**
 806  * A function to return the read side of the piped log pipe
 807  * @param pl The piped log structure
 808  * @return The native file descriptor
 809  */
 810 AP_DECLARE(apr_file_t *) ap_piped_log_read_fd(piped_log *pl);
 811
 812 /**
 813  * A function to return the write side of the piped log pipe
 814  * @param pl The piped log structure
 815  * @return The native file descriptor
 816  */
 817 AP_DECLARE(apr_file_t *) ap_piped_log_write_fd(piped_log *pl);
 818
 819 /**
 820  * hook method to generate unique id for connection or request
 821  * @ingroup hooks
 822  * @param c the conn_rec of the connections
 823  * @param r the request_req (may be NULL)
 824  * @param id the place where to store the unique id
 825  * @return OK or DECLINE
 826  */
 827 AP_DECLARE_HOOK(int, generate_log_id,
 828                 (const conn_rec *c, const request_rec *r, const char **id))
 829
 830
 831 #ifdef __cplusplus
 832 }
 833 #endif
 834
 835 #endif  /* !APACHE_HTTP_LOG_H */
 836 /** @} */