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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @brief Apache Logging library
21 * @defgroup APACHE_CORE_LOG Logging library
22 * @ingroup APACHE_CORE
26 #ifndef APACHE_HTTP_LOG_H
27 #define APACHE_HTTP_LOG_H
33 #include "apr_thread_proc.h"
34 #include "http_config.h"
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 */
60 #define APLOG_LEVELMASK 15 /* mask off the level value */
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 */
81 #define APLOG_LEVELMASK 15 /* mask off the level value */
85 /* APLOG_NOERRNO is ignored and should not be used. It will be
86 * removed in a future release of Apache.
88 #define APLOG_NOERRNO (APLOG_LEVELMASK + 1)
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.
102 #define APLOG_TOCLIENT ((APLOG_LEVELMASK + 1) * 2)
104 /* normal but significant condition on startup, usually printed to stderr */
105 #define APLOG_STARTUP ((APLOG_LEVELMASK + 1) * 4)
107 #ifndef DEFAULT_LOGLEVEL
108 #define DEFAULT_LOGLEVEL APLOG_WARNING
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.
117 #define APLOGNO(n) "AH" #n ": "
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
126 * @see APLOG_MODULE_INDEX
129 #define APLOG_NO_MODULE -1
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).
139 #else /* __cplusplus */
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.
148 static int * const aplog_module_index;
149 #endif /* __cplusplus */
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
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
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 */
173 * APLOG_MAX_LOGLEVEL can be defined to remove logging above some
174 * specified level at compile time.
176 * This requires a C99 compiler.
179 #define APLOG_MAX_LOGLEVEL
181 #ifndef APLOG_MAX_LOGLEVEL
182 #define APLOG_MODULE_IS_LEVEL(s,module_index,level) \
183 ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) || \
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) ) )
200 #define APLOG_MODULE_IS_LEVEL(s,module_index,level) \
201 ( (((level)&APLOG_LEVELMASK) <= APLOG_MAX_LOGLEVEL) && \
202 ( (((level)&APLOG_LEVELMASK) <= APLOG_NOTICE) || \
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) ) ) )
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)
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)
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)
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)
266 AP_DECLARE_DATA extern int ap_default_loglevel;
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.
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
277 * @see APLOG_MODULE_INDEX
281 * @see ap_log_cserror
283 #define APLOG_MARK __FILE__,__LINE__,APLOG_MODULE_INDEX
286 * Set up for logging to stderr.
287 * @param p The pool to allocate out of
289 AP_DECLARE(void) ap_open_stderr_log(apr_pool_t *p);
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
296 AP_DECLARE(apr_status_t) ap_replace_stderr_log(apr_pool_t *p,
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
308 int ap_open_logs(apr_pool_t *pconf, apr_pool_t *plog,
309 apr_pool_t *ptemp, server_rec *s_main);
312 * Perform special processing for piped loggers in MPM child
316 * @note ap_logs_child_init is not for use by modules; it is an
317 * internal core function
319 void ap_logs_child_init(apr_pool_t *p, server_rec *s);
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.
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
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
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
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, ...);
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__); \
370 #define ap_log_error ap_log_error_
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)));
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
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, ...);
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)
412 #define ap_log_perror ap_log_perror_
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)));
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
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
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, ...);
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__); \
454 #define ap_log_rerror ap_log_rerror_
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)));
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
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
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, ...);
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__); \
498 #define ap_log_cerror ap_log_cerror_
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)));
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
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, ...);
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, \
546 #define ap_log_cserror ap_log_cserror_
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)));
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.
562 * Processing flags for ap_log_data() et al
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
568 #define AP_LOG_DATA_DEFAULT 0
569 #define AP_LOG_DATA_SHOW_OFFSET 1
572 * ap_log_data() - log buffers which are not related to a particular request
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
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);
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__); \
604 #define ap_log_data ap_log_data_
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);
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
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);
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, r, ...) \
638 do { if (APLOG_R_MODULE_IS_LEVEL(r, mi, level)) \
639 ap_log_rdata_(file, line, mi, level, r, __VA_ARGS__); \
642 #define ap_log_rdata ap_log_rdata_
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);
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
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);
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__); \
680 #define ap_log_cdata ap_log_cdata_
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);
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
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);
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__); \
721 #define ap_log_cdata ap_log_cdata_
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);
730 * Convert stderr to the error log
731 * @param s The current server
733 AP_DECLARE(void) ap_error_log2stderr(server_rec *s);
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.
741 AP_DECLARE(void) ap_log_command_line(apr_pool_t *p, server_rec *s);
744 * Log common (various) MPM shared data at startup.
745 * @param s The server_rec of the error log we want to log to.
746 * Misc commonly logged data is logged to that server's error log.
748 AP_DECLARE(void) ap_log_mpm_common(server_rec *s);
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.
756 AP_DECLARE(void) ap_log_pid(apr_pool_t *p, const char *fname);
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.
764 AP_DECLARE(void) ap_remove_pid(apr_pool_t *p, const char *fname);
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)
773 AP_DECLARE(apr_status_t) ap_read_pid(apr_pool_t *p, const char *filename, pid_t *mypid);
775 /** @see piped_log */
776 typedef struct piped_log piped_log;
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
786 AP_DECLARE(piped_log *) ap_open_piped_log(apr_pool_t *p, const char *program);
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
795 AP_DECLARE(piped_log *) ap_open_piped_log_ex(apr_pool_t *p,
797 apr_cmdtype_e cmdtype);
800 * Close the piped log and kill the logging process
801 * @param pl The piped log structure
803 AP_DECLARE(void) ap_close_piped_log(piped_log *pl);
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
810 AP_DECLARE(apr_file_t *) ap_piped_log_read_fd(piped_log *pl);
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
817 AP_DECLARE(apr_file_t *) ap_piped_log_write_fd(piped_log *pl);
820 * hook method to generate unique id for connection or request
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
827 AP_DECLARE_HOOK(int, generate_log_id,
828 (const conn_rec *c, const request_rec *r, const char **id))
835 #endif /* !APACHE_HTTP_LOG_H */