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 CORE HTTP Daemon
21 * @defgroup APACHE_CORE_HTTPD Core HTTP Daemon
22 * @ingroup APACHE_CORE
26 #ifndef APACHE_HTTP_CORE_H
27 #define APACHE_HTTP_CORE_H
31 #include "apr_optional.h"
32 #include "util_filter.h"
34 #include "apr_tables.h"
36 #include "http_config.h"
38 #if APR_HAVE_STRUCT_RLIMIT
40 #include <sys/resource.h>
48 /* ****************************************************************
50 * The most basic server code is encapsulated in a single module
51 * known as the core, which is just *barely* functional enough to
52 * serve documents, though not terribly well.
54 * Largely for NCSA back-compatibility reasons, the core needs to
55 * make pieces of its config structures available to other modules.
56 * The accessors are declared here, along with the interpretation
57 * of one of them (allow_options).
61 * @defgroup APACHE_CORE_HTTPD_ACESSORS Acessors
63 * @brief File/Directory Accessor directives
70 /** Indexes directive */
72 /** SSI is enabled without exec= permission */
73 #define OPT_INCLUDES 2
74 /** FollowSymLinks directive */
75 #define OPT_SYM_LINKS 4
76 /** ExecCGI directive */
78 /** directive unset */
80 /** SSI exec= permission is permitted, iff OPT_INCLUDES is also set */
81 #define OPT_INC_WITH_EXEC 32
82 /** SymLinksIfOwnerMatch directive */
83 #define OPT_SYM_OWNER 64
84 /** MultiViews directive */
87 #define OPT_ALL (OPT_INDEXES|OPT_INCLUDES|OPT_INC_WITH_EXEC|OPT_SYM_LINKS|OPT_EXECCGI)
91 * @defgroup get_remote_host Remote Host Resolution
92 * @ingroup APACHE_CORE_HTTPD
95 /** REMOTE_HOST returns the hostname, or NULL if the hostname
96 * lookup fails. It will force a DNS lookup according to the
97 * HostnameLookups setting.
99 #define REMOTE_HOST (0)
101 /** REMOTE_NAME returns the hostname, or the dotted quad if the
102 * hostname lookup fails. It will force a DNS lookup according
103 * to the HostnameLookups setting.
105 #define REMOTE_NAME (1)
107 /** REMOTE_NOLOOKUP is like REMOTE_NAME except that a DNS lookup is
110 #define REMOTE_NOLOOKUP (2)
112 /** REMOTE_DOUBLE_REV will always force a DNS lookup, and also force
113 * a double reverse lookup, regardless of the HostnameLookups
114 * setting. The result is the (double reverse checked) hostname,
115 * or NULL if any of the lookups fail.
117 #define REMOTE_DOUBLE_REV (3)
119 /** @} // get_remote_host */
121 /** all of the requirements must be met */
122 #define SATISFY_ALL 0
123 /** any of the requirements must be met */
124 #define SATISFY_ANY 1
125 /** There are no applicable satisfy lines */
126 #define SATISFY_NOSPEC 2
128 /** Make sure we don't write less than 8000 bytes at any one time.
130 #define AP_MIN_BYTES_TO_WRITE 8000
132 /** default maximum of internal redirects */
133 # define AP_DEFAULT_MAX_INTERNAL_REDIRECTS 10
135 /** default maximum subrequest nesting level */
136 # define AP_DEFAULT_MAX_SUBREQ_DEPTH 10
139 * Retrieve the value of Options for this request
140 * @param r The current request
141 * @return the Options bitmask
143 AP_DECLARE(int) ap_allow_options(request_rec *r);
146 * Retrieve the value of the AllowOverride for this request
147 * @param r The current request
148 * @return the overrides bitmask
150 AP_DECLARE(int) ap_allow_overrides(request_rec *r);
153 * Retrieve the document root for this server
154 * @param r The current request
155 * @warning Don't use this! If your request went through a Userdir, or
156 * something like that, it'll screw you. But it's back-compatible...
157 * @return The document root
159 AP_DECLARE(const char *) ap_document_root(request_rec *r);
162 * Lookup the remote client's DNS name or IP address
163 * @ingroup get_remote_host
164 * @param conn The current connection
165 * @param dir_config The directory config vector from the request
166 * @param type The type of lookup to perform. One of:
168 * REMOTE_HOST returns the hostname, or NULL if the hostname
169 * lookup fails. It will force a DNS lookup according to the
170 * HostnameLookups setting.
171 * REMOTE_NAME returns the hostname, or the dotted quad if the
172 * hostname lookup fails. It will force a DNS lookup according
173 * to the HostnameLookups setting.
174 * REMOTE_NOLOOKUP is like REMOTE_NAME except that a DNS lookup is
176 * REMOTE_DOUBLE_REV will always force a DNS lookup, and also force
177 * a double reverse lookup, regardless of the HostnameLookups
178 * setting. The result is the (double reverse checked)
179 * hostname, or NULL if any of the lookups fail.
181 * @param str_is_ip unless NULL is passed, this will be set to non-zero on output when an IP address
183 * @return The remote hostname
185 AP_DECLARE(const char *) ap_get_remote_host(conn_rec *conn, void *dir_config, int type, int *str_is_ip);
188 * Retrieve the login name of the remote user. Undef if it could not be
190 * @param r The current request
191 * @return The user logged in to the client machine
193 AP_DECLARE(const char *) ap_get_remote_logname(request_rec *r);
195 /* Used for constructing self-referencing URLs, and things like SERVER_PORT,
199 * build a fully qualified URL from the uri and information in the request rec
200 * @param p The pool to allocate the URL from
201 * @param uri The path to the requested file
202 * @param r The current request
203 * @return A fully qualified URL
205 AP_DECLARE(char *) ap_construct_url(apr_pool_t *p, const char *uri, request_rec *r);
208 * Get the current server name from the request
209 * @param r The current request
210 * @return the server name
212 AP_DECLARE(const char *) ap_get_server_name(request_rec *r);
215 * Get the current server name from the request for the purposes
216 * of using in a URL. If the server name is an IPv6 literal
217 * address, it will be returned in URL format (e.g., "[fe80::1]").
218 * @param r The current request
219 * @return the server name
221 AP_DECLARE(const char *) ap_get_server_name_for_url(request_rec *r);
224 * Get the current server port
225 * @param r The current request
226 * @return The server's port
228 AP_DECLARE(apr_port_t) ap_get_server_port(const request_rec *r);
231 * Return the limit on bytes in request msg body
232 * @param r The current request
233 * @return the maximum number of bytes in the request msg body
235 AP_DECLARE(apr_off_t) ap_get_limit_req_body(const request_rec *r);
238 * Return the limit on bytes in XML request msg body
239 * @param r The current request
240 * @return the maximum number of bytes in XML request msg body
242 AP_DECLARE(apr_size_t) ap_get_limit_xml_body(const request_rec *r);
245 * Install a custom response handler for a given status
246 * @param r The current request
247 * @param status The status for which the custom response should be used
248 * @param string The custom response. This can be a static string, a file
251 AP_DECLARE(void) ap_custom_response(request_rec *r, int status, const char *string);
254 * Check if the current request is beyond the configured max. number of redirects or subrequests
255 * @param r The current request
256 * @return true (is exceeded) or false
258 AP_DECLARE(int) ap_is_recursion_limit_exceeded(const request_rec *r);
261 * Check for a definition from the server command line
262 * @param name The define to check for
263 * @return 1 if defined, 0 otherwise
265 AP_DECLARE(int) ap_exists_config_define(const char *name);
266 /* FIXME! See STATUS about how */
267 AP_DECLARE_NONSTD(int) ap_core_translate(request_rec *r);
269 /* Authentication stuff. This is one of the places where compatibility
270 * with the old config files *really* hurts; they don't discriminate at
271 * all between different authentication schemes, meaning that we need
272 * to maintain common state for all of them in the core, and make it
273 * available to the other modules through interfaces.
276 /** @see require_line */
277 typedef struct require_line require_line;
280 * @brief A structure to keep track of authorization requirements
282 struct require_line {
283 /** Where the require line is in the config file. */
284 apr_int64_t method_mask;
285 /** The complete string from the command line */
290 * Return the type of authorization required for this request
291 * @param r The current request
292 * @return The authorization required
294 AP_DECLARE(const char *) ap_auth_type(request_rec *r);
297 * Return the current Authorization realm
298 * @param r The current request
299 * @return The current authorization realm
301 AP_DECLARE(const char *) ap_auth_name(request_rec *r);
304 * How the requires lines must be met.
305 * @param r The current request
306 * @return How the requirements must be met. One of:
308 * SATISFY_ANY -- any of the requirements must be met.
309 * SATISFY_ALL -- all of the requirements must be met.
310 * SATISFY_NOSPEC -- There are no applicable satisfy lines
313 AP_DECLARE(int) ap_satisfies(request_rec *r);
316 * Core is also unlike other modules in being implemented in more than
317 * one file... so, data structures are declared here, even though most of
318 * the code that cares really is in http_core.c. Also, another accessor.
320 AP_DECLARE_DATA extern module core_module;
323 * Accessor for core_module's specific data. Equivalent to
324 * ap_get_module_config(cv, &core_module) but more efficient.
325 * @param cv The vector in which the modules configuration is stored.
326 * usually r->per_dir_config or s->module_config
327 * @return The module-specific data
329 AP_DECLARE(void *) ap_get_core_module_config(const ap_conf_vector_t *cv);
332 * Accessor to set core_module's specific data. Equivalent to
333 * ap_set_module_config(cv, &core_module, val) but more efficient.
334 * @param cv The vector in which the modules configuration is stored.
335 * usually r->per_dir_config or s->module_config
336 * @param val The module-specific data to set
338 AP_DECLARE(void) ap_set_core_module_config(ap_conf_vector_t *cv, void *val);
340 /** Get the socket from the core network filter. This should be used instead of
341 * accessing the core connection config directly.
342 * @param c The connection record
345 AP_DECLARE(apr_socket_t *) ap_get_conn_socket(conn_rec *c);
348 #define AP_CORE_MODULE_INDEX 0
349 #define ap_get_core_module_config(v) \
350 (((void **)(v))[AP_CORE_MODULE_INDEX])
351 #define ap_set_core_module_config(v, val) \
352 ((((void **)(v))[AP_CORE_MODULE_INDEX]) = (val))
354 #define AP_CORE_MODULE_INDEX (AP_DEBUG_ASSERT(core_module.module_index == 0), 0)
358 * @brief Per-request configuration
361 /** bucket brigade used by getline for look-ahead and
362 * ap_get_client_block for holding left-over request body */
363 struct apr_bucket_brigade *bb;
365 /** an array of per-request working data elements, accessed
366 * by ID using ap_get_request_note()
367 * (Use ap_register_request_note() during initialization
372 /** Custom response strings registered via ap_custom_response(),
373 * or NULL; check per-dir config if nothing found here
375 char **response_code_strings; /* from ap_custom_response(), not from
379 /** per-request document root of the server. This allows mass vhosting
380 * modules better compatibility with some scripts. Normally the
381 * context_* info should be used instead */
382 const char *document_root;
385 * more fine-grained context information which is set by modules like
386 * mod_alias and mod_userdir
388 /** the context root directory on disk for the current resource,
389 * without trailing slash
391 const char *context_document_root;
392 /** the URI prefix that corresponds to the context_document_root directory,
393 * without trailing slash
395 const char *context_prefix;
397 /** There is a script processor installed on the output filter chain,
398 * so it needs the default_handler to deliver a (script) file into
399 * the chain so it can process it. Normally, default_handler only
400 * serves files on a GET request (assuming the file is actual content),
401 * since other methods are not content-retrieval. This flag overrides
402 * that behavior, stating that the "content" is actually a script and
403 * won't actually be delivered as the response for the non-GET method.
407 /** Should addition of charset= be suppressed for this request?
409 int suppress_charset;
410 } core_request_config;
412 /* Standard entries that are guaranteed to be accessible via
413 * ap_get_request_note() for each request (additional entries
414 * can be added with ap_register_request_note())
416 #define AP_NOTE_DIRECTORY_WALK 0
417 #define AP_NOTE_LOCATION_WALK 1
418 #define AP_NOTE_FILE_WALK 2
419 #define AP_NOTE_IF_WALK 3
420 #define AP_NUM_STD_NOTES 4
423 * Reserve an element in the core_request_config->notes array
424 * for some application-specific data
425 * @return An integer key that can be passed to ap_get_request_note()
426 * during request processing to access this element for the
429 AP_DECLARE(apr_size_t) ap_register_request_note(void);
432 * Retrieve a pointer to an element in the core_request_config->notes array
433 * @param r The request
434 * @param note_num A key for the element: either a value obtained from
435 * ap_register_request_note() or one of the predefined AP_NOTE_*
437 * @return NULL if the note_num is invalid, otherwise a pointer to the
438 * requested note element.
439 * @remark At the start of a request, each note element is NULL. The
440 * handle provided by ap_get_request_note() is a pointer-to-pointer
441 * so that the caller can point the element to some app-specific
442 * data structure. The caller should guarantee that any such
443 * structure will last as long as the request itself.
445 AP_DECLARE(void **) ap_get_request_note(request_rec *r, apr_size_t note_num);
448 typedef unsigned char allow_options_t;
449 typedef unsigned int overrides_t;
452 * Bits of info that go into making an ETag for a file
453 * document. Why a long? Because char historically
454 * proved too short for Options, and int can be different
455 * sizes on different platforms.
457 typedef unsigned long etag_components_t;
460 #define ETAG_NONE (1 << 0)
461 #define ETAG_MTIME (1 << 1)
462 #define ETAG_INODE (1 << 2)
463 #define ETAG_SIZE (1 << 3)
464 #define ETAG_ALL (ETAG_MTIME | ETAG_INODE | ETAG_SIZE)
465 /* This is the default value used */
466 #define ETAG_BACKWARD (ETAG_MTIME | ETAG_SIZE)
469 * @brief Server Signature Enumeration
476 } server_signature_e;
479 * @brief Per-directory configuration
482 /** path of the directory/regex/etc. see also d_is_fnmatch/absolute below */
484 /** the number of slashes in d */
485 unsigned d_components;
487 /** If (opts & OPT_UNSET) then no absolute assignment to options has
489 * invariant: (opts_add & opts_remove) == 0
490 * Which said another way means that the last relative (options + or -)
491 * assignment made to each bit is recorded in exactly one of opts_add
494 allow_options_t opts;
495 allow_options_t opts_add;
496 allow_options_t opts_remove;
497 overrides_t override;
498 allow_options_t override_opts;
500 /* Used to be the custom response config. No longer used. */
501 char **response_code_strings; /* from ErrorDocument, not from
502 * ap_custom_response() */
504 /* Hostname resolution etc */
505 #define HOSTNAME_LOOKUP_OFF 0
506 #define HOSTNAME_LOOKUP_ON 1
507 #define HOSTNAME_LOOKUP_DOUBLE 2
508 #define HOSTNAME_LOOKUP_UNSET 3
509 unsigned int hostname_lookups : 4;
511 unsigned int content_md5 : 2; /* calculate Content-MD5? */
513 #define USE_CANONICAL_NAME_OFF (0)
514 #define USE_CANONICAL_NAME_ON (1)
515 #define USE_CANONICAL_NAME_DNS (2)
516 #define USE_CANONICAL_NAME_UNSET (3)
517 unsigned use_canonical_name : 2;
519 /* since is_fnmatch(conf->d) was being called so frequently in
520 * directory_walk() and its relatives, this field was created and
521 * is set to the result of that call.
523 unsigned d_is_fnmatch : 1;
525 /* should we force a charset on any outgoing parameterless content-type?
526 * if so, which charset?
528 #define ADD_DEFAULT_CHARSET_OFF (0)
529 #define ADD_DEFAULT_CHARSET_ON (1)
530 #define ADD_DEFAULT_CHARSET_UNSET (2)
531 unsigned add_default_charset : 2;
532 const char *add_default_charset_name;
534 /* System Resource Control */
536 struct rlimit *limit_cpu;
538 #if defined (RLIMIT_DATA) || defined (RLIMIT_VMEM) || defined(RLIMIT_AS)
539 struct rlimit *limit_mem;
542 struct rlimit *limit_nproc;
544 apr_off_t limit_req_body; /* limit on bytes in request msg body */
545 long limit_xml_body; /* limit on bytes in XML request msg body */
547 /* logging options */
549 server_signature_e server_signature;
552 apr_array_header_t *sec_file;
553 apr_array_header_t *sec_if;
556 const char *mime_type; /* forced with ForceType */
557 const char *handler; /* forced with SetHandler */
558 const char *output_filters; /* forced with SetOutputFilters */
559 const char *input_filters; /* forced with SetInputFilters */
560 int accept_path_info; /* forced with AcceptPathInfo */
563 * What attributes/data should be included in ETag generation?
565 etag_components_t etag_bits;
566 etag_components_t etag_add;
567 etag_components_t etag_remove;
570 * Run-time performance tuning
572 #define ENABLE_MMAP_OFF (0)
573 #define ENABLE_MMAP_ON (1)
574 #define ENABLE_MMAP_UNSET (2)
575 unsigned int enable_mmap : 2; /* whether files in this dir can be mmap'ed */
577 #define ENABLE_SENDFILE_OFF (0)
578 #define ENABLE_SENDFILE_ON (1)
579 #define ENABLE_SENDFILE_UNSET (2)
580 unsigned int enable_sendfile : 2; /* files in this dir can be sendfile'ed */
582 #define USE_CANONICAL_PHYS_PORT_OFF (0)
583 #define USE_CANONICAL_PHYS_PORT_ON (1)
584 #define USE_CANONICAL_PHYS_PORT_UNSET (2)
585 unsigned int use_canonical_phys_port : 2;
587 unsigned int allow_encoded_slashes : 1; /* URLs may contain %2f w/o being
588 * pitched indiscriminately */
589 unsigned int decode_encoded_slashes : 1; /* whether to decode encoded slashes in URLs */
591 #define AP_CONDITION_IF 1
592 #define AP_CONDITION_ELSE 2
593 #define AP_CONDITION_ELSEIF (AP_CONDITION_ELSE|AP_CONDITION_IF)
594 unsigned int condition_ifelse : 2; /* is this an <If>, <ElseIf>, or <Else> */
596 ap_expr_info_t *condition; /* Conditionally merge <If> sections */
598 /** per-dir log config */
599 struct ap_logconf *log;
601 /** Table of directives allowed per AllowOverrideList */
602 apr_table_t *override_list;
604 #define AP_MAXRANGES_UNSET -1
605 #define AP_MAXRANGES_DEFAULT -2
606 #define AP_MAXRANGES_UNLIMITED -3
607 #define AP_MAXRANGES_NORANGES 0
608 /** Number of Ranges before returning HTTP_OK. **/
610 /** Max number of Range overlaps (merges) allowed **/
612 /** Max number of Range reversals (eg: 200-300, 100-125) allowed **/
615 unsigned int allow_encoded_slashes_set : 1;
616 unsigned int decode_encoded_slashes_set : 1;
618 /** Named back references */
619 apr_array_header_t *refs;
621 #define AP_CGI_PASS_AUTH_OFF (0)
622 #define AP_CGI_PASS_AUTH_ON (1)
623 #define AP_CGI_PASS_AUTH_UNSET (2)
624 /** CGIPassAuth: Whether HTTP authorization headers will be passed to
625 * scripts as CGI variables; affects all modules calling
626 * ap_add_common_vars(), as well as any others using this field as
629 unsigned int cgi_pass_auth : 2;
631 /** Custom response config with expression support. The hash table
632 * contains compiled expressions keyed against the custom response
635 apr_hash_t *response_code_exprs;
639 /* macro to implement off by default behaviour */
640 #define AP_SENDFILE_ENABLED(x) \
641 ((x) == ENABLE_SENDFILE_ON ? APR_SENDFILE_ENABLED : 0)
643 /* Per-server core configuration */
649 /* Name translations --- we want the core to be able to do *something*
650 * so it's at least a minimally functional web server on its own (and
651 * can be tested that way). But let's keep it to the bare minimum:
653 const char *ap_document_root;
658 apr_array_header_t *sec_dir;
659 apr_array_header_t *sec_url;
661 /* recursion backstopper */
662 int redirect_limit; /* maximum number of internal redirects */
663 int subreq_limit; /* maximum nesting level of subrequests */
665 const char *protocol;
666 apr_table_t *accf_map;
668 /* array of ap_errorlog_format_item for error log format string */
669 apr_array_header_t *error_log_format;
671 * two arrays of arrays of ap_errorlog_format_item for additional information
672 * logged to the error log once per connection/request
674 apr_array_header_t *error_log_conn;
675 apr_array_header_t *error_log_req;
678 #define AP_TRACE_UNSET -1
679 #define AP_TRACE_DISABLE 0
680 #define AP_TRACE_ENABLE 1
681 #define AP_TRACE_EXTENDED 2
683 #define AP_MERGE_TRAILERS_UNSET 0
684 #define AP_MERGE_TRAILERS_ENABLE 1
685 #define AP_MERGE_TRAILERS_DISABLE 2
688 apr_array_header_t *conn_log_level;
690 #define AP_HTTP09_UNSET 0
691 #define AP_HTTP09_ENABLE 1
692 #define AP_HTTP09_DISABLE 2
695 #define AP_HTTP_CONFORMANCE_UNSET 0
696 #define AP_HTTP_CONFORMANCE_LIBERAL 1
697 #define AP_HTTP_CONFORMANCE_STRICT 2
698 #define AP_HTTP_CONFORMANCE_LOGONLY 4
699 char http_conformance;
701 #define AP_HTTP_CL_HEAD_ZERO_UNSET 0
702 #define AP_HTTP_CL_HEAD_ZERO_ENABLE 1
703 #define AP_HTTP_CL_HEAD_ZERO_DISABLE 2
704 int http_cl_head_zero;
706 #define AP_HTTP_EXPECT_STRICT_UNSET 0
707 #define AP_HTTP_EXPECT_STRICT_ENABLE 1
708 #define AP_HTTP_EXPECT_STRICT_DISABLE 2
709 int http_expect_strict;
712 apr_array_header_t *protocols;
713 int protocols_honor_order;
714 } core_server_config;
716 /* for AddOutputFiltersByType in core.c */
717 void ap_add_output_filters_by_type(request_rec *r);
719 /* for http_config.c */
720 void ap_core_reorder_directories(apr_pool_t *, server_rec *);
723 AP_CORE_DECLARE(void) ap_add_per_dir_conf(server_rec *s, void *dir_config);
724 AP_CORE_DECLARE(void) ap_add_per_url_conf(server_rec *s, void *url_config);
725 AP_CORE_DECLARE(void) ap_add_file_conf(apr_pool_t *p, core_dir_config *conf, void *url_config);
726 AP_CORE_DECLARE(const char *) ap_add_if_conf(apr_pool_t *p, core_dir_config *conf, void *url_config);
727 AP_CORE_DECLARE_NONSTD(const char *) ap_limit_section(cmd_parms *cmd, void *dummy, const char *arg);
729 /* Core filters; not exported. */
730 apr_status_t ap_core_input_filter(ap_filter_t *f, apr_bucket_brigade *b,
731 ap_input_mode_t mode, apr_read_type_e block,
732 apr_off_t readbytes);
733 apr_status_t ap_core_output_filter(ap_filter_t *f, apr_bucket_brigade *b);
736 AP_DECLARE(const char*) ap_get_server_protocol(server_rec* s);
737 AP_DECLARE(void) ap_set_server_protocol(server_rec* s, const char* proto);
739 typedef struct core_output_filter_ctx core_output_filter_ctx_t;
740 typedef struct core_filter_ctx core_ctx_t;
742 typedef struct core_net_rec {
743 /** Connection to the client */
744 apr_socket_t *client_socket;
746 /** connection record */
749 core_output_filter_ctx_t *out_ctx;
754 * Insert the network bucket into the core input filter's input brigade.
755 * This hook is intended for MPMs or protocol modules that need to do special
757 * @param c The connection
758 * @param bb The brigade to insert the bucket into
759 * @param socket The socket to put into a bucket
760 * @return AP_DECLINED if the current function does not handle this connection,
761 * APR_SUCCESS or an error otherwise.
763 AP_DECLARE_HOOK(apr_status_t, insert_network_bucket,
764 (conn_rec *c, apr_bucket_brigade *bb, apr_socket_t *socket))
766 /* ----------------------------------------------------------------------
768 * Runtime status/management
784 const char *description;
786 ap_mgmt_type_e vtype;
790 /* Handles for core filters */
791 AP_DECLARE_DATA extern ap_filter_rec_t *ap_subreq_core_filter_handle;
792 AP_DECLARE_DATA extern ap_filter_rec_t *ap_core_output_filter_handle;
793 AP_DECLARE_DATA extern ap_filter_rec_t *ap_content_length_filter_handle;
794 AP_DECLARE_DATA extern ap_filter_rec_t *ap_core_input_filter_handle;
797 * This hook provdes a way for modules to provide metrics/statistics about
798 * their operational status.
800 * @param p A pool to use to create entries in the hash table
801 * @param val The name of the parameter(s) that is wanted. This is
802 * tree-structured would be in the form ('*' is all the tree,
803 * 'module.*' all of the module , 'module.foo.*', or
805 * @param ht The hash table to store the results. Keys are item names, and
806 * the values point to ap_mgmt_item_t structures.
809 AP_DECLARE_HOOK(int, get_mgmt_items,
810 (apr_pool_t *p, const char * val, apr_hash_t *ht))
812 /* ---------------------------------------------------------------------- */
814 /* ----------------------------------------------------------------------
816 * I/O logging with mod_logio
819 APR_DECLARE_OPTIONAL_FN(void, ap_logio_add_bytes_out,
820 (conn_rec *c, apr_off_t bytes));
822 APR_DECLARE_OPTIONAL_FN(void, ap_logio_add_bytes_in,
823 (conn_rec *c, apr_off_t bytes));
825 APR_DECLARE_OPTIONAL_FN(apr_off_t, ap_logio_get_last_bytes, (conn_rec *c));
827 /* ----------------------------------------------------------------------
833 * The info structure passed to callback functions of errorlog handlers.
834 * Not all information is available in all contexts. In particular, all
835 * pointers may be NULL.
837 typedef struct ap_errorlog_info {
838 /** current server_rec.
839 * Should be preferred over c->base_server and r->server
843 /** current conn_rec.
844 * Should be preferred over r->connection
848 /** current request_rec. */
849 const request_rec *r;
850 /** r->main if r is a subrequest, otherwise equal to r */
851 const request_rec *rmain;
853 /** pool passed to ap_log_perror, NULL otherwise */
856 /** name of source file where the log message was produced, NULL if N/A. */
858 /** line number in the source file, 0 if N/A */
861 /** module index of module that produced the log message, APLOG_NO_MODULE if N/A. */
863 /** log level of error message (flags like APLOG_STARTUP have been removed), -1 if N/A */
866 /** apr error status related to the log message, 0 if no error */
869 /** 1 if logging using provider, 0 otherwise */
871 /** 1 if APLOG_STARTUP was set for the log message, 0 otherwise */
874 /** message format */
878 #define AP_ERRORLOG_PROVIDER_GROUP "error_log_writer"
879 #define AP_ERRORLOG_PROVIDER_VERSION "0"
880 #define AP_ERRORLOG_DEFAULT_PROVIDER "file"
882 /** add APR_EOL_STR to the end of log message */
883 #define AP_ERRORLOG_PROVIDER_ADD_EOL_STR 1
885 typedef struct ap_errorlog_provider ap_errorlog_provider;
887 struct ap_errorlog_provider {
888 /** Initializes the error log writer.
889 * @param p The pool to create any storage from
890 * @param s Server for which the logger is initialized
891 * @return Pointer to handle passed later to writer() function
892 * @note On success, the provider must return non-NULL, even if
893 * the handle is not necessary when the writer() function is
894 * called. On failure, the provider should log a startup error
895 * message and return NULL to abort httpd startup.
897 void * (*init)(apr_pool_t *p, server_rec *s);
899 /** Logs the error message to external error log.
900 * @param info Context of the error message
901 * @param handle Handle created by init() function
902 * @param errstr Error message
903 * @param len Length of the error message
905 apr_status_t (*writer)(const ap_errorlog_info *info, void *handle,
906 const char *errstr, apr_size_t len);
908 /** Checks syntax of ErrorLog directive argument.
909 * @param cmd The config directive
910 * @param arg ErrorLog directive argument (or the empty string if
911 * no argument was provided)
912 * @return Error message or NULL on success
913 * @remark The argument will be stored in the error_fname field
914 * of server_rec for access later.
916 const char * (*parse_errorlog_arg)(cmd_parms *cmd, const char *arg);
918 /** a combination of the AP_ERRORLOG_PROVIDER_* flags */
923 * callback function prototype for a external errorlog handler
924 * @note To avoid unbounded memory usage, these functions must not allocate
925 * memory from the server, connection, or request pools. If an errorlog
926 * handler absolutely needs a pool to pass to other functions, it must create
927 * and destroy a sub-pool.
929 typedef int ap_errorlog_handler_fn_t(const ap_errorlog_info *info,
930 const char *arg, char *buf, int buflen);
933 * Register external errorlog handler
934 * @param p config pool to use
935 * @param tag the new format specifier (i.e. the letter after the %)
936 * @param handler the handler function
937 * @param flags flags (reserved, set to 0)
939 AP_DECLARE(void) ap_register_errorlog_handler(apr_pool_t *p, char *tag,
940 ap_errorlog_handler_fn_t *handler,
943 typedef struct ap_errorlog_handler {
944 ap_errorlog_handler_fn_t *func;
945 int flags; /* for future extensions */
946 } ap_errorlog_handler;
948 /** item starts a new field */
949 #define AP_ERRORLOG_FLAG_FIELD_SEP 1
950 /** item is the actual error message */
951 #define AP_ERRORLOG_FLAG_MESSAGE 2
952 /** skip whole line if item is zero-length */
953 #define AP_ERRORLOG_FLAG_REQUIRED 4
954 /** log zero-length item as '-' */
955 #define AP_ERRORLOG_FLAG_NULL_AS_HYPHEN 8
958 /** ap_errorlog_handler function */
959 ap_errorlog_handler_fn_t *func;
960 /** argument passed to item in {} */
962 /** a combination of the AP_ERRORLOG_* flags */
964 /** only log item if the message's log level is higher than this */
965 unsigned int min_loglevel;
966 } ap_errorlog_format_item;
969 * hook method to log error messages
971 * @param info pointer to ap_errorlog_info struct which contains all
973 * @param errstr the (unformatted) message to log
974 * @warning Allocating from the usual pools (pool, info->c->pool, info->p->pool)
975 * must be avoided because it can cause memory leaks.
976 * Use a subpool if necessary.
978 AP_DECLARE_HOOK(void, error_log, (const ap_errorlog_info *info,
981 AP_CORE_DECLARE(void) ap_register_log_hooks(apr_pool_t *p);
982 AP_CORE_DECLARE(void) ap_register_config_hooks(apr_pool_t *p);
984 /* ----------------------------------------------------------------------
986 * ident lookups with mod_ident
989 APR_DECLARE_OPTIONAL_FN(const char *, ap_ident_lookup,
992 /* ----------------------------------------------------------------------
994 * authorization values with mod_authz_core
997 APR_DECLARE_OPTIONAL_FN(int, authz_some_auth_required, (request_rec *r));
998 APR_DECLARE_OPTIONAL_FN(const char *, authn_ap_auth_type, (request_rec *r));
999 APR_DECLARE_OPTIONAL_FN(const char *, authn_ap_auth_name, (request_rec *r));
1001 /* ----------------------------------------------------------------------
1003 * authorization values with mod_access_compat
1006 APR_DECLARE_OPTIONAL_FN(int, access_compat_ap_satisfies, (request_rec *r));
1008 /* ---------------------------------------------------------------------- */
1010 /** Query the server for some state information
1011 * @param query_code Which information is requested
1012 * @return the requested state information
1014 AP_DECLARE(int) ap_state_query(int query_code);
1017 * possible values for query_code in ap_state_query()
1020 /** current status of the server */
1021 #define AP_SQ_MAIN_STATE 0
1022 /** are we going to serve requests or are we just testing/dumping config */
1023 #define AP_SQ_RUN_MODE 1
1024 /** generation of the top-level apache parent */
1025 #define AP_SQ_CONFIG_GEN 2
1028 * return values for ap_state_query()
1031 /** return value for unknown query_code */
1032 #define AP_SQ_NOT_SUPPORTED -1
1034 /* values returned for AP_SQ_MAIN_STATE */
1035 /** before the config preflight */
1036 #define AP_SQ_MS_INITIAL_STARTUP 1
1037 /** initial configuration run for setting up log config, etc. */
1038 #define AP_SQ_MS_CREATE_PRE_CONFIG 2
1039 /** tearing down configuration */
1040 #define AP_SQ_MS_DESTROY_CONFIG 3
1041 /** normal configuration run */
1042 #define AP_SQ_MS_CREATE_CONFIG 4
1043 /** running the MPM */
1044 #define AP_SQ_MS_RUN_MPM 5
1045 /** cleaning up for exit */
1046 #define AP_SQ_MS_EXITING 6
1048 /* values returned for AP_SQ_RUN_MODE */
1049 /** command line not yet parsed */
1050 #define AP_SQ_RM_UNKNOWN 1
1051 /** normal operation (server requests or signal server) */
1052 #define AP_SQ_RM_NORMAL 2
1053 /** config test only */
1054 #define AP_SQ_RM_CONFIG_TEST 3
1055 /** only dump some parts of the config */
1056 #define AP_SQ_RM_CONFIG_DUMP 4
1059 /* ---------------------------------------------------------------------- */
1061 /** Create a slave connection
1062 * @param c The connection to create the slave connection from/for
1063 * @return The slave connection
1065 AP_CORE_DECLARE(conn_rec *) ap_create_slave_connection(conn_rec *c);
1071 #endif /* !APACHE_HTTP_CORE_H */