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.
17 #ifndef APACHE_HTTP_LOG_H
18 #define APACHE_HTTP_LOG_H
24 #include "apr_thread_proc.h"
27 * @package Apache logging library
37 #define APLOG_EMERG LOG_EMERG /* system is unusable */
38 #define APLOG_ALERT LOG_ALERT /* action must be taken immediately */
39 #define APLOG_CRIT LOG_CRIT /* critical conditions */
40 #define APLOG_ERR LOG_ERR /* error conditions */
41 #define APLOG_WARNING LOG_WARNING /* warning conditions */
42 #define APLOG_NOTICE LOG_NOTICE /* normal but significant condition */
43 #define APLOG_INFO LOG_INFO /* informational */
44 #define APLOG_DEBUG LOG_DEBUG /* debug-level messages */
46 #define APLOG_LEVELMASK LOG_PRIMASK /* mask off the level value */
50 #define APLOG_EMERG 0 /* system is unusable */
51 #define APLOG_ALERT 1 /* action must be taken immediately */
52 #define APLOG_CRIT 2 /* critical conditions */
53 #define APLOG_ERR 3 /* error conditions */
54 #define APLOG_WARNING 4 /* warning conditions */
55 #define APLOG_NOTICE 5 /* normal but significant condition */
56 #define APLOG_INFO 6 /* informational */
57 #define APLOG_DEBUG 7 /* debug-level messages */
59 #define APLOG_LEVELMASK 7 /* mask off the level value */
63 /* APLOG_NOERRNO is ignored and should not be used. It will be
64 * removed in a future release of Apache.
66 #define APLOG_NOERRNO (APLOG_LEVELMASK + 1)
68 /* Use APLOG_TOCLIENT on ap_log_rerror() to give content
69 * handlers the option of including the error text in the
70 * ErrorDocument sent back to the client. Setting APLOG_TOCLIENT
71 * will cause the error text to be saved in the request_rec->notes
72 * table, keyed to the string "error-notes", if and only if:
73 * - the severity level of the message is APLOG_WARNING or greater
74 * - there are no other "error-notes" set in request_rec->notes
75 * Once error-notes is set, it is up to the content handler to
76 * determine whether this text should be sent back to the client.
77 * Note: Client generated text streams sent back to the client MUST
78 * be escaped to prevent CSS attacks.
80 #define APLOG_TOCLIENT ((APLOG_LEVELMASK + 1) * 2)
82 /* normal but significant condition on startup, usually printed to stderr */
83 #define APLOG_STARTUP ((APLOG_LEVELMASK + 1) * 4)
85 #ifndef DEFAULT_LOGLEVEL
86 #define DEFAULT_LOGLEVEL APLOG_WARNING
89 extern int AP_DECLARE_DATA ap_default_loglevel;
91 #define APLOG_MARK __FILE__,__LINE__
94 * Set up for logging to stderr.
95 * @param p The pool to allocate out of
97 AP_DECLARE(void) ap_open_stderr_log(apr_pool_t *p);
100 * Replace logging to stderr with logging to the given file.
101 * @param p The pool to allocate out of
102 * @param file Name of the file to log stderr output
104 AP_DECLARE(apr_status_t) ap_replace_stderr_log(apr_pool_t *p,
108 * Open the error log and replace stderr with it.
109 * @param pconf Not used
110 * @param plog The pool to allocate the logs from
111 * @param ptemp Pool used for temporary allocations
112 * @param s_main The main server
113 * @tip ap_open_logs isn't expected to be used by modules, it is
114 * an internal core function
116 int ap_open_logs(apr_pool_t *pconf, apr_pool_t *plog,
117 apr_pool_t *ptemp, server_rec *s_main);
122 * Perform special processing for piped loggers in MPM child
126 * @tip ap_logs_child_init is not for use by modules; it is an
127 * internal core function
129 void ap_logs_child_init(apr_pool_t *p, server_rec *s);
131 #endif /* CORE_PRIVATE */
134 * The primary logging functions, ap_log_error, ap_log_rerror, ap_log_cerror,
135 * and ap_log_perror use a printf style format string to build the log message.
136 * It is VERY IMPORTANT that you not include any raw data from the network,
137 * such as the request-URI or request header fields, within the format
138 * string. Doing so makes the server vulnerable to a denial-of-service
139 * attack and other messy behavior. Instead, use a simple format string
140 * like "%s", followed by the string containing the untrusted data.
144 * ap_log_error() - log messages which are not related to a particular
145 * request or connection. This uses a printf-like format to log messages
147 * @param file The file in which this function is called
148 * @param line The line number on which this function is called
149 * @param level The level of this error message
150 * @param status The status code from the previous command
151 * @param s The server on which we are logging
152 * @param fmt The format string
153 * @param ... The arguments to use to fill out fmt.
154 * @tip Use APLOG_MARK to fill out file and line
155 * @tip If a request_rec is available, use that with ap_log_rerror()
156 * in preference to calling this function. Otherwise, if a conn_rec is
157 * available, use that with ap_log_cerror() in preference to calling
159 * @warning It is VERY IMPORTANT that you not include any raw data from
160 * the network, such as the request-URI or request header fields, within
161 * the format string. Doing so makes the server vulnerable to a
162 * denial-of-service attack and other messy behavior. Instead, use a
163 * simple format string like "%s", followed by the string containing the
165 * @deffunc void ap_log_error(const char *file, int line, int level, apr_status_t status, const server_rec *s, const char *fmt, ...)
167 AP_DECLARE(void) ap_log_error(const char *file, int line, int level,
168 apr_status_t status, const server_rec *s,
169 const char *fmt, ...)
170 __attribute__((format(printf,6,7)));
173 * ap_log_perror() - log messages which are not related to a particular
174 * request, connection, or virtual server. This uses a printf-like
175 * format to log messages to the error_log.
176 * @param file The file in which this function is called
177 * @param line The line number on which this function is called
178 * @param level The level of this error message
179 * @param status The status code from the previous command
180 * @param p The pool which we are logging for
181 * @param fmt The format string
182 * @param ... The arguments to use to fill out fmt.
183 * @tip Use APLOG_MARK to fill out file and line
184 * @warning It is VERY IMPORTANT that you not include any raw data from
185 * the network, such as the request-URI or request header fields, within
186 * the format string. Doing so makes the server vulnerable to a
187 * denial-of-service attack and other messy behavior. Instead, use a
188 * simple format string like "%s", followed by the string containing the
190 * @deffunc void ap_log_perror(const char *file, int line, int level, apr_status_t status, apr_pool_t *p, const char *fmt, ...)
192 AP_DECLARE(void) ap_log_perror(const char *file, int line, int level,
193 apr_status_t status, apr_pool_t *p,
194 const char *fmt, ...)
195 __attribute__((format(printf,6,7)));
198 * ap_log_rerror() - log messages which are related to a particular
199 * request. This uses a a printf-like format to log messages to the
201 * @param file The file in which this function is called
202 * @param line The line number on which this function is called
203 * @param level The level of this error message
204 * @param status The status code from the previous command
205 * @param r The request which we are logging for
206 * @param fmt The format string
207 * @param ... The arguments to use to fill out fmt.
208 * @tip Use APLOG_MARK to fill out file and line
209 * @warning It is VERY IMPORTANT that you not include any raw data from
210 * the network, such as the request-URI or request header fields, within
211 * the format string. Doing so makes the server vulnerable to a
212 * denial-of-service attack and other messy behavior. Instead, use a
213 * simple format string like "%s", followed by the string containing the
215 * @deffunc void ap_log_rerror(const char *file, int line, int level, apr_status_t status, const request_rec *r, const char *fmt, ...)
217 AP_DECLARE(void) ap_log_rerror(const char *file, int line, int level,
218 apr_status_t status, const request_rec *r,
219 const char *fmt, ...)
220 __attribute__((format(printf,6,7)));
223 * ap_log_cerror() - log messages which are related to a particular
224 * connection. This uses a a printf-like format to log messages to the
226 * @param file The file in which this function is called
227 * @param line The line number on which this function is called
228 * @param level The level of this error message
229 * @param status The status code from the previous command
230 * @param c The connection which we are logging for
231 * @param fmt The format string
232 * @param ... The arguments to use to fill out fmt.
233 * @tip Use APLOG_MARK to fill out file and line
234 * @tip If a request_rec is available, use that with ap_log_rerror()
235 * in preference to calling this function.
236 * @warning It is VERY IMPORTANT that you not include any raw data from
237 * the network, such as the request-URI or request header fields, within
238 * the format string. Doing so makes the server vulnerable to a
239 * denial-of-service attack and other messy behavior. Instead, use a
240 * simple format string like "%s", followed by the string containing the
242 * @note ap_log_cerror() is available starting with Apache 2.0.55.
243 * @deffunc void ap_log_cerror(const char *file, int line, int level, apr_status_t status, const conn_rec *c, const char *fmt, ...)
245 AP_DECLARE(void) ap_log_cerror(const char *file, int line, int level,
246 apr_status_t status, const conn_rec *c,
247 const char *fmt, ...)
248 __attribute__((format(printf,6,7)));
251 * Convert stderr to the error log
252 * @param s The current server
253 * @deffunc void ap_error_log2stderr(server_rec *s)
255 AP_DECLARE(void) ap_error_log2stderr(server_rec *s);
258 * Log the current pid of the parent process
259 * @param p The pool to use for logging
260 * @param fname The name of the file to log to
262 AP_DECLARE(void) ap_log_pid(apr_pool_t *p, const char *fname);
265 * Retrieve the pid from a pidfile.
266 * @param p The pool to use for logging
267 * @param filename The name of the file containing the pid
268 * @param mypid Pointer to pid_t (valid only if return APR_SUCCESS)
270 AP_DECLARE(apr_status_t) ap_read_pid(apr_pool_t *p, const char *filename, pid_t *mypid);
272 typedef struct piped_log piped_log;
275 * The piped logging structure. Piped logs are used to move functionality
276 * out of the main server. For example, log rotation is done with piped logs.
279 /** The pool to use for the piped log */
281 /** The pipe between the server and the logging process */
283 /* XXX - an #ifdef that needs to be eliminated from public view. Shouldn't
285 #ifdef AP_HAVE_RELIABLE_PIPED_LOGS
286 /** The name of the program the logging process is running */
288 /** The pid of the logging process */
294 * Open the piped log process
295 * @param p The pool to allocate out of
296 * @param program The program to run in the logging process
297 * @return The piped log structure
298 * @deffunc piped_log *ap_open_piped_log(apr_pool_t *p, const char *program)
300 AP_DECLARE(piped_log *) ap_open_piped_log(apr_pool_t *p, const char *program);
303 * Close the piped log and kill the logging process
304 * @param pl The piped log structure
305 * @deffunc void ap_close_piped_log(piped_log *pl)
307 AP_DECLARE(void) ap_close_piped_log(piped_log *pl);
310 * A macro to access the read side of the piped log pipe
311 * @param pl The piped log structure
312 * @return The native file descriptor
313 * @deffunc ap_piped_log_read_fd(pl)
315 #define ap_piped_log_read_fd(pl) ((pl)->fds[0])
318 * A macro to access the write side of the piped log pipe
319 * @param pl The piped log structure
320 * @return The native file descriptor
321 * @deffunc ap_piped_log_read_fd(pl)
323 #define ap_piped_log_write_fd(pl) ((pl)->fds[1])
325 AP_DECLARE_HOOK(void, error_log, (const char *file, int line, int level,
326 apr_status_t status, const server_rec *s,
327 const request_rec *r, apr_pool_t *pool,
334 #endif /* !APACHE_HTTP_LOG_H */