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_config.h 19 * @brief Apache Configuration 20 * 21 * @defgroup APACHE_CORE_CONFIG Configuration 22 * @ingroup APACHE_CORE 23 * @{ 24 */ 25 26#ifndef APACHE_HTTP_CONFIG_H 27#define APACHE_HTTP_CONFIG_H 28 29#include "apr_hooks.h" 30#include "util_cfgtree.h" 31 32#ifdef __cplusplus 33extern "C" { 34#endif 35 36/* 37 * The central data structures around here... 38 */ 39 40/* Command dispatch structures... */ 41 42/** 43 * How the directives arguments should be parsed. 44 * @remark Note that for all of these except RAW_ARGS, the config routine is 45 * passed a freshly allocated string which can be modified or stored 46 * or whatever... 47 */ 48enum cmd_how { 49 RAW_ARGS, /**< cmd_func parses command line itself */ 50 TAKE1, /**< one argument only */ 51 TAKE2, /**< two arguments only */ 52 ITERATE, /**< one argument, occuring multiple times 53 * (e.g., IndexIgnore) 54 */ 55 ITERATE2, /**< two arguments, 2nd occurs multiple times 56 * (e.g., AddIcon) 57 */ 58 FLAG, /**< One of 'On' or 'Off' */ 59 NO_ARGS, /**< No args at all, e.g. </Directory> */ 60 TAKE12, /**< one or two arguments */ 61 TAKE3, /**< three arguments only */ 62 TAKE23, /**< two or three arguments */ 63 TAKE123, /**< one, two or three arguments */ 64 TAKE13, /**< one or three arguments */ 65 TAKE_ARGV /**< an argc and argv are passed */ 66}; 67/** 68 * This structure is passed to a command which is being invoked, 69 * to carry a large variety of miscellaneous data which is all of 70 * use to *somebody*... 71 */ 72typedef struct cmd_parms_struct cmd_parms; 73 74#if defined(AP_HAVE_DESIGNATED_INITIALIZER) || defined(DOXYGEN) 75 76/** 77 * All the types of functions that can be used in directives 78 * @internal 79 */ 80typedef union { 81 /** function to call for a no-args */ 82 const char *(*no_args) (cmd_parms *parms, void *mconfig); 83 /** function to call for a raw-args */ 84 const char *(*raw_args) (cmd_parms *parms, void *mconfig, 85 const char *args); 86 /** function to call for a argv/argc */ 87 const char *(*take_argv) (cmd_parms *parms, void *mconfig, 88 int argc, char *const argv[]); 89 /** function to call for a take1 */ 90 const char *(*take1) (cmd_parms *parms, void *mconfig, const char *w); 91 /** function to call for a take2 */ 92 const char *(*take2) (cmd_parms *parms, void *mconfig, const char *w, 93 const char *w2); 94 /** function to call for a take3 */ 95 const char *(*take3) (cmd_parms *parms, void *mconfig, const char *w, 96 const char *w2, const char *w3); 97 /** function to call for a flag */ 98 const char *(*flag) (cmd_parms *parms, void *mconfig, int on); 99} cmd_func; 100 101/** This configuration directive does not take any arguments */ 102# define AP_NO_ARGS func.no_args 103/** This configuration directive will handle it's own parsing of arguments*/ 104# define AP_RAW_ARGS func.raw_args 105/** This configuration directive will handle it's own parsing of arguments*/ 106# define AP_TAKE_ARGV func.take_argv 107/** This configuration directive takes 1 argument*/ 108# define AP_TAKE1 func.take1 109/** This configuration directive takes 2 arguments */ 110# define AP_TAKE2 func.take2 111/** This configuration directive takes 3 arguments */ 112# define AP_TAKE3 func.take3 113/** This configuration directive takes a flag (on/off) as a argument*/ 114# define AP_FLAG func.flag 115 116/** method of declaring a directive with no arguments */ 117# define AP_INIT_NO_ARGS(directive, func, mconfig, where, help) \ 118 { directive, { .no_args=func }, mconfig, where, RAW_ARGS, help } 119/** method of declaring a directive with raw argument parsing */ 120# define AP_INIT_RAW_ARGS(directive, func, mconfig, where, help) \ 121 { directive, { .raw_args=func }, mconfig, where, RAW_ARGS, help } 122/** method of declaring a directive with raw argument parsing */ 123# define AP_INIT_TAKE_ARGV(directive, func, mconfig, where, help) \ 124 { directive, { .take_argv=func }, mconfig, where, TAKE_ARGV, help } 125/** method of declaring a directive which takes 1 argument */ 126# define AP_INIT_TAKE1(directive, func, mconfig, where, help) \ 127 { directive, { .take1=func }, mconfig, where, TAKE1, help } 128/** method of declaring a directive which takes multiple arguments */ 129# define AP_INIT_ITERATE(directive, func, mconfig, where, help) \ 130 { directive, { .take1=func }, mconfig, where, ITERATE, help } 131/** method of declaring a directive which takes 2 arguments */ 132# define AP_INIT_TAKE2(directive, func, mconfig, where, help) \ 133 { directive, { .take2=func }, mconfig, where, TAKE2, help } 134/** method of declaring a directive which takes 1 or 2 arguments */ 135# define AP_INIT_TAKE12(directive, func, mconfig, where, help) \ 136 { directive, { .take2=func }, mconfig, where, TAKE12, help } 137/** method of declaring a directive which takes multiple 2 arguments */ 138# define AP_INIT_ITERATE2(directive, func, mconfig, where, help) \ 139 { directive, { .take2=func }, mconfig, where, ITERATE2, help } 140/** method of declaring a directive which takes 1 or 3 arguments */ 141# define AP_INIT_TAKE13(directive, func, mconfig, where, help) \ 142 { directive, { .take3=func }, mconfig, where, TAKE13, help } 143/** method of declaring a directive which takes 2 or 3 arguments */ 144# define AP_INIT_TAKE23(directive, func, mconfig, where, help) \ 145 { directive, { .take3=func }, mconfig, where, TAKE23, help } 146/** method of declaring a directive which takes 1 to 3 arguments */ 147# define AP_INIT_TAKE123(directive, func, mconfig, where, help) \ 148 { directive, { .take3=func }, mconfig, where, TAKE123, help } 149/** method of declaring a directive which takes 3 arguments */ 150# define AP_INIT_TAKE3(directive, func, mconfig, where, help) \ 151 { directive, { .take3=func }, mconfig, where, TAKE3, help } 152/** method of declaring a directive which takes a flag (on/off) as a argument*/ 153# define AP_INIT_FLAG(directive, func, mconfig, where, help) \ 154 { directive, { .flag=func }, mconfig, where, FLAG, help } 155 156#else /* AP_HAVE_DESIGNATED_INITIALIZER */ 157 158typedef const char *(*cmd_func) (); 159 160# define AP_NO_ARGS func 161# define AP_RAW_ARGS func 162# define AP_TAKE_ARGV func 163# define AP_TAKE1 func 164# define AP_TAKE2 func 165# define AP_TAKE3 func 166# define AP_FLAG func 167 168# define AP_INIT_NO_ARGS(directive, func, mconfig, where, help) \ 169 { directive, func, mconfig, where, RAW_ARGS, help } 170# define AP_INIT_RAW_ARGS(directive, func, mconfig, where, help) \ 171 { directive, func, mconfig, where, RAW_ARGS, help } 172# define AP_INIT_TAKE_ARGV(directive, func, mconfig, where, help) \ 173 { directive, func, mconfig, where, TAKE_ARGV, help } 174# define AP_INIT_TAKE1(directive, func, mconfig, where, help) \ 175 { directive, func, mconfig, where, TAKE1, help } 176# define AP_INIT_ITERATE(directive, func, mconfig, where, help) \ 177 { directive, func, mconfig, where, ITERATE, help } 178# define AP_INIT_TAKE2(directive, func, mconfig, where, help) \ 179 { directive, func, mconfig, where, TAKE2, help } 180# define AP_INIT_TAKE12(directive, func, mconfig, where, help) \ 181 { directive, func, mconfig, where, TAKE12, help } 182# define AP_INIT_ITERATE2(directive, func, mconfig, where, help) \ 183 { directive, func, mconfig, where, ITERATE2, help } 184# define AP_INIT_TAKE13(directive, func, mconfig, where, help) \ 185 { directive, func, mconfig, where, TAKE13, help } 186# define AP_INIT_TAKE23(directive, func, mconfig, where, help) \ 187 { directive, func, mconfig, where, TAKE23, help } 188# define AP_INIT_TAKE123(directive, func, mconfig, where, help) \ 189 { directive, func, mconfig, where, TAKE123, help } 190# define AP_INIT_TAKE3(directive, func, mconfig, where, help) \ 191 { directive, func, mconfig, where, TAKE3, help } 192# define AP_INIT_FLAG(directive, func, mconfig, where, help) \ 193 { directive, func, mconfig, where, FLAG, help } 194 195#endif /* AP_HAVE_DESIGNATED_INITIALIZER */ 196 197/** 198 * The command record structure. Each modules can define a table of these 199 * to define the directives it will implement. 200 */ 201typedef struct command_struct command_rec; 202struct command_struct { 203 /** Name of this command */ 204 const char *name; 205 /** The function to be called when this directive is parsed */ 206 cmd_func func; 207 /** Extra data, for functions which implement multiple commands... */ 208 void *cmd_data; 209 /** What overrides need to be allowed to enable this command. */ 210 int req_override; 211 /** What the command expects as arguments 212 * @defvar cmd_how args_how*/ 213 enum cmd_how args_how; 214 215 /** 'usage' message, in case of syntax errors */ 216 const char *errmsg; 217}; 218 219/** 220 * @defgroup ConfigDirectives Allowed locations for configuration directives. 221 * 222 * The allowed locations for a configuration directive are the union of 223 * those indicated by each set bit in the req_override mask. 224 * 225 * @{ 226 */ 227#define OR_NONE 0 /**< *.conf is not available anywhere in this override */ 228#define OR_LIMIT 1 /**< *.conf inside <Directory> or <Location> 229 and .htaccess when AllowOverride Limit */ 230#define OR_OPTIONS 2 /**< *.conf anywhere 231 and .htaccess when AllowOverride Options */ 232#define OR_FILEINFO 4 /**< *.conf anywhere 233 and .htaccess when AllowOverride FileInfo */ 234#define OR_AUTHCFG 8 /**< *.conf inside <Directory> or <Location> 235 and .htaccess when AllowOverride AuthConfig */ 236#define OR_INDEXES 16 /**< *.conf anywhere 237 and .htaccess when AllowOverride Indexes */ 238#define OR_UNSET 32 /**< unset a directive (in Allow) */ 239#define ACCESS_CONF 64 /**< *.conf inside <Directory> or <Location> */ 240#define RSRC_CONF 128 /**< *.conf outside <Directory> or <Location> */ 241#define EXEC_ON_READ 256 /**< force directive to execute a command 242 which would modify the configuration (like including another 243 file, or IFModule */ 244/** this directive can be placed anywhere */ 245#define OR_ALL (OR_LIMIT|OR_OPTIONS|OR_FILEINFO|OR_AUTHCFG|OR_INDEXES) 246 247/** @} */ 248 249/** 250 * This can be returned by a function if they don't wish to handle 251 * a command. Make it something not likely someone will actually use 252 * as an error code. 253 */ 254#define DECLINE_CMD "\a\b" 255 256/** Common structure for reading of config files / passwd files etc. */ 257typedef struct ap_configfile_t ap_configfile_t; 258struct ap_configfile_t { 259 int (*getch) (void *param); /**< a getc()-like function */ 260 void *(*getstr) (void *buf, size_t bufsiz, void *param); 261 /**< a fgets()-like function */ 262 int (*close) (void *param); /**< a close handler function */ 263 void *param; /**< the argument passed to getch/getstr/close */ 264 const char *name; /**< the filename / description */ 265 unsigned line_number; /**< current line number, starting at 1 */ 266}; 267 268/** 269 * This structure is passed to a command which is being invoked, 270 * to carry a large variety of miscellaneous data which is all of 271 * use to *somebody*... 272 */ 273struct cmd_parms_struct { 274 /** Argument to command from cmd_table */ 275 void *info; 276 /** Which allow-override bits are set */ 277 int override; 278 /** Which methods are <Limit>ed */ 279 apr_int64_t limited; 280 /** methods which are limited */ 281 apr_array_header_t *limited_xmethods; 282 /** methods which are xlimited */ 283 ap_method_list_t *xlimited; 284 285 /** Config file structure. */ 286 ap_configfile_t *config_file; 287 /** the directive specifying this command */ 288 ap_directive_t *directive; 289 290 /** Pool to allocate new storage in */ 291 apr_pool_t *pool; 292 /** Pool for scratch memory; persists during configuration, but 293 * wiped before the first request is served... */ 294 apr_pool_t *temp_pool; 295 /** Server_rec being configured for */ 296 server_rec *server; 297 /** If configuring for a directory, pathname of that directory. 298 * NOPE! That's what it meant previous to the existance of <Files>, 299 * <Location> and regex matching. Now the only usefulness that can be 300 * derived from this field is whether a command is being called in a 301 * server context (path == NULL) or being called in a dir context 302 * (path != NULL). */ 303 char *path; 304 /** configuration command */ 305 const command_rec *cmd; 306 307 /** per_dir_config vector passed to handle_command */ 308 struct ap_conf_vector_t *context; 309 /** directive with syntax error */ 310 const ap_directive_t *err_directive; 311 312 /** Which allow-override-opts bits are set */ 313 int override_opts; 314}; 315 316/** 317 * Module structures. Just about everything is dispatched through 318 * these, directly or indirectly (through the command and handler 319 * tables). 320 */ 321typedef struct module_struct module; 322struct module_struct { 323 /** API version, *not* module version; check that module is 324 * compatible with this version of the server. 325 */ 326 int version; 327 /** API minor version. Provides API feature milestones. Not checked 328 * during module init */ 329 int minor_version; 330 /** Index to this modules structures in config vectors. */ 331 int module_index; 332 333 /** The name of the module's C file */ 334 const char *name; 335 /** The handle for the DSO. Internal use only */ 336 void *dynamic_load_handle; 337 338 /** A pointer to the next module in the list 339 * @defvar module_struct *next */ 340 struct module_struct *next; 341 342 /** Magic Cookie to identify a module structure; It's mainly 343 * important for the DSO facility (see also mod_so). */ 344 unsigned long magic; 345 346 /** Function to allow MPMs to re-write command line arguments. This 347 * hook is only available to MPMs. 348 * @param The process that the server is running in. 349 */ 350 void (*rewrite_args) (process_rec *process); 351 /** Function to allow all modules to create per directory configuration 352 * structures. 353 * @param p The pool to use for all allocations. 354 * @param dir The directory currently being processed. 355 * @return The per-directory structure created 356 */ 357 void *(*create_dir_config) (apr_pool_t *p, char *dir); 358 /** Function to allow all modules to merge the per directory configuration 359 * structures for two directories. 360 * @param p The pool to use for all allocations. 361 * @param base_conf The directory structure created for the parent directory. 362 * @param new_conf The directory structure currently being processed. 363 * @return The new per-directory structure created 364 */ 365 void *(*merge_dir_config) (apr_pool_t *p, void *base_conf, void *new_conf); 366 /** Function to allow all modules to create per server configuration 367 * structures. 368 * @param p The pool to use for all allocations. 369 * @param s The server currently being processed. 370 * @return The per-server structure created 371 */ 372 void *(*create_server_config) (apr_pool_t *p, server_rec *s); 373 /** Function to allow all modules to merge the per server configuration 374 * structures for two servers. 375 * @param p The pool to use for all allocations. 376 * @param base_conf The directory structure created for the parent directory. 377 * @param new_conf The directory structure currently being processed. 378 * @return The new per-directory structure created 379 */ 380 void *(*merge_server_config) (apr_pool_t *p, void *base_conf, 381 void *new_conf); 382 383 /** A command_rec table that describes all of the directives this module 384 * defines. */ 385 const command_rec *cmds; 386 387 /** A hook to allow modules to hook other points in the request processing. 388 * In this function, modules should call the ap_hook_*() functions to 389 * register an interest in a specific step in processing the current 390 * request. 391 * @param p the pool to use for all allocations 392 */ 393 void (*register_hooks) (apr_pool_t *p); 394}; 395 396/** 397 * @defgroup ModuleInit Module structure initializers 398 * 399 * Initializer for the first few module slots, which are only 400 * really set up once we start running. Note that the first two slots 401 * provide a version check; this should allow us to deal with changes to 402 * the API. The major number should reflect changes to the API handler table 403 * itself or removal of functionality. The minor number should reflect 404 * additions of functionality to the existing API. (the server can detect 405 * an old-format module, and either handle it back-compatibly, or at least 406 * signal an error). See src/include/ap_mmn.h for MMN version history. 407 * @{ 408 */ 409 410/** The one used in Apache 1.3, which will deliberately cause an error */ 411#define STANDARD_MODULE_STUFF this_module_needs_to_be_ported_to_apache_2_0 412 413/** Use this in all standard modules */ 414#define STANDARD20_MODULE_STUFF MODULE_MAGIC_NUMBER_MAJOR, \ 415 MODULE_MAGIC_NUMBER_MINOR, \ 416 -1, \ 417 __FILE__, \ 418 NULL, \ 419 NULL, \ 420 MODULE_MAGIC_COOKIE, \ 421 NULL /* rewrite args spot */ 422 423/** Use this only in MPMs */ 424#define MPM20_MODULE_STUFF MODULE_MAGIC_NUMBER_MAJOR, \ 425 MODULE_MAGIC_NUMBER_MINOR, \ 426 -1, \ 427 __FILE__, \ 428 NULL, \ 429 NULL, \ 430 MODULE_MAGIC_COOKIE 431 432/** @} */ 433 434/* CONFIGURATION VECTOR FUNCTIONS */ 435 436/** configuration vector structure */ 437typedef struct ap_conf_vector_t ap_conf_vector_t; 438 439/** 440 * Generic accessors for other modules to get at their own module-specific 441 * data 442 * @param conf_vector The vector in which the modules configuration is stored. 443 * usually r->per_dir_config or s->module_config 444 * @param m The module to get the data for. 445 * @return The module-specific data 446 */ 447AP_DECLARE(void *) ap_get_module_config(const ap_conf_vector_t *cv, 448 const module *m); 449 450/** 451 * Generic accessors for other modules to set at their own module-specific 452 * data 453 * @param conf_vector The vector in which the modules configuration is stored. 454 * usually r->per_dir_config or s->module_config 455 * @param m The module to set the data for. 456 * @param val The module-specific data to set 457 */ 458AP_DECLARE(void) ap_set_module_config(ap_conf_vector_t *cv, const module *m, 459 void *val); 460 461#if !defined(AP_DEBUG) 462 463#define ap_get_module_config(v,m) \ 464 (((void **)(v))[(m)->module_index]) 465#define ap_set_module_config(v,m,val) \ 466 ((((void **)(v))[(m)->module_index]) = (val)) 467 468#endif /* AP_DEBUG */ 469 470 471/** 472 * Generic command handling function for strings 473 * @param cmd The command parameters for this directive 474 * @param struct_ptr pointer into a given type 475 * @param arg The argument to the directive 476 * @return An error string or NULL on success 477 */ 478AP_DECLARE_NONSTD(const char *) ap_set_string_slot(cmd_parms *cmd, 479 void *struct_ptr, 480 const char *arg); 481 482/** 483 * Generic command handling function for integers 484 * @param cmd The command parameters for this directive 485 * @param struct_ptr pointer into a given type 486 * @param arg The argument to the directive 487 * @return An error string or NULL on success 488 */ 489AP_DECLARE_NONSTD(const char *) ap_set_int_slot(cmd_parms *cmd, 490 void *struct_ptr, 491 const char *arg); 492 493/** 494 * Return true if the specified method is limited by being listed in 495 * a <Limit> container, or by *not* being listed in a <LimiteExcept> 496 * container. 497 * 498 * @param method Pointer to a string specifying the method to check. 499 * @param cmd Pointer to the cmd_parms structure passed to the 500 * directive handler. 501 * @return 0 if the method is not limited in the current scope 502 */ 503AP_DECLARE(int) ap_method_is_limited(cmd_parms *cmd, const char *method); 504 505/** 506 * Generic command handling function for strings, always sets the value 507 * to a lowercase string 508 * @param cmd The command parameters for this directive 509 * @param struct_ptr pointer into a given type 510 * @param arg The argument to the directive 511 * @return An error string or NULL on success 512 */ 513AP_DECLARE_NONSTD(const char *) ap_set_string_slot_lower(cmd_parms *cmd, 514 void *struct_ptr, 515 const char *arg); 516/** 517 * Generic command handling function for flags 518 * @param cmd The command parameters for this directive 519 * @param struct_ptr pointer into a given type 520 * @param arg The argument to the directive (either 1 or 0) 521 * @return An error string or NULL on success 522 */ 523AP_DECLARE_NONSTD(const char *) ap_set_flag_slot(cmd_parms *cmd, 524 void *struct_ptr, 525 int arg); 526/** 527 * Generic command handling function for files 528 * @param cmd The command parameters for this directive 529 * @param struct_ptr pointer into a given type 530 * @param arg The argument to the directive 531 * @return An error string or NULL on success 532 */ 533AP_DECLARE_NONSTD(const char *) ap_set_file_slot(cmd_parms *cmd, 534 void *struct_ptr, 535 const char *arg); 536/** 537 * Generic command handling function to respond with cmd->help as an error 538 * @param cmd The command parameters for this directive 539 * @param struct_ptr pointer into a given type 540 * @param arg The argument to the directive 541 * @return The cmd->help value as the error string 542 * @tip This allows simple declarations such as; 543 * <pre> 544 * AP_INIT_RAW_ARGS("Foo", ap_set_deprecated, NULL, OR_ALL, 545 * "The Foo directive is no longer supported, use Bar"), 546 * </pre> 547 */ 548AP_DECLARE_NONSTD(const char *) ap_set_deprecated(cmd_parms *cmd, 549 void *struct_ptr, 550 const char *arg); 551/** 552 * For modules which need to read config files, open logs, etc. this returns 553 * the canonical form of fname made absolute to ap_server_root. 554 * @param p pool to allocate data from 555 * @param fname The file name 556 */ 557AP_DECLARE(char *) ap_server_root_relative(apr_pool_t *p, const char *fname); 558 559/* Finally, the hook for dynamically loading modules in... */ 560 561/** 562 * Add a module to the server 563 * @param m The module structure of the module to add 564 * @param p The pool of the same lifetime as the module 565 */ 566AP_DECLARE(const char *) ap_add_module(module *m, apr_pool_t *p); 567 568/** 569 * Remove a module from the server. There are some caveats: 570 * when the module is removed, its slot is lost so all the current 571 * per-dir and per-server configurations are invalid. So we should 572 * only ever call this function when you are invalidating almost 573 * all our current data. I.e. when doing a restart. 574 * @param m the module structure of the module to remove 575 */ 576AP_DECLARE(void) ap_remove_module(module *m); 577/** 578 * Add a module to the chained modules list and the list of loaded modules 579 * @param m The module structure of the module to add 580 * @param p The pool with the same lifetime as the module 581 */ 582AP_DECLARE(const char *) ap_add_loaded_module(module *mod, apr_pool_t *p); 583/** 584 * Remove a module fromthe chained modules list and the list of loaded modules 585 * @param m the module structure of the module to remove 586 */ 587AP_DECLARE(void) ap_remove_loaded_module(module *mod); 588/** 589 * Find the name of the specified module 590 * @param m The module to get the name for 591 * @return the name of the module 592 */ 593AP_DECLARE(const char *) ap_find_module_name(module *m); 594/** 595 * Find a module based on the name of the module 596 * @param name the name of the module 597 * @return the module structure if found, NULL otherwise 598 */ 599AP_DECLARE(module *) ap_find_linked_module(const char *name); 600 601/** 602 * Open a ap_configfile_t as apr_file_t 603 * @param ret_cfg open ap_configfile_t struct pointer 604 * @param p The pool to allocate the structure from 605 * @param name the name of the file to open 606 */ 607AP_DECLARE(apr_status_t) ap_pcfg_openfile(ap_configfile_t **ret_cfg, 608 apr_pool_t *p, const char *name); 609 610/** 611 * Allocate a ap_configfile_t handle with user defined functions and params 612 * @param p The pool to allocate from 613 * @param descr The name of the file 614 * @param param The argument passed to getch/getstr/close 615 * @param getc_func The getch function 616 * @param gets_func The getstr function 617 * @param close_func The close function 618 */ 619AP_DECLARE(ap_configfile_t *) ap_pcfg_open_custom(apr_pool_t *p, 620 const char *descr, 621 void *param, 622 int(*getc_func)(void*), 623 void *(*gets_func) (void *buf, size_t bufsiz, void *param), 624 int(*close_func)(void *param)); 625 626/** 627 * Read one line from open ap_configfile_t, strip LF, increase line number 628 * @param buf place to store the line read 629 * @param bufsize size of the buffer 630 * @param cfp File to read from 631 * @return 1 on success, 0 on failure 632 */ 633AP_DECLARE(int) ap_cfg_getline(char *buf, size_t bufsize, ap_configfile_t *cfp); 634 635/** 636 * Read one char from open configfile_t, increase line number upon LF 637 * @param cfp The file to read from 638 * @return the character read 639 */ 640AP_DECLARE(int) ap_cfg_getc(ap_configfile_t *cfp); 641 642/** 643 * Detach from open ap_configfile_t, calling the close handler 644 * @param cfp The file to close 645 * @return 1 on sucess, 0 on failure 646 */ 647AP_DECLARE(int) ap_cfg_closefile(ap_configfile_t *cfp); 648 649/** 650 * Read all data between the current <foo> and the matching </foo>. All 651 * of this data is forgotten immediately. 652 * @param cmd The cmd_parms to pass to the directives inside the container 653 * @param directive The directive name to read until 654 * @return Error string on failure, NULL on success 655 */ 656AP_DECLARE(const char *) ap_soak_end_container(cmd_parms *cmd, char *directive); 657 658/** 659 * Read all data between the current <foo> and the matching </foo> and build 660 * a config tree from it 661 * @param p pool to allocate from 662 * @param temp_pool Temporary pool to allocate from 663 * @param parms The cmd_parms to pass to all directives read 664 * @param current The current node in the tree 665 * @param curr_parent The current parent node 666 * @param orig_directive The directive to read until hit. 667 * @return Error string on failure, NULL on success 668*/ 669AP_DECLARE(const char *) ap_build_cont_config(apr_pool_t *p, 670 apr_pool_t *temp_pool, 671 cmd_parms *parms, 672 ap_directive_t **current, 673 ap_directive_t **curr_parent, 674 char *orig_directive); 675 676/** 677 * Build a config tree from a config file 678 * @param parms The cmd_parms to pass to all of the directives in the file 679 * @param conf_pool The pconf pool 680 * @param temp_pool The temporary pool 681 * @param conftree Place to store the root node of the config tree 682 * @return Error string on erro, NULL otherwise 683 */ 684AP_DECLARE(const char *) ap_build_config(cmd_parms *parms, 685 apr_pool_t *conf_pool, 686 apr_pool_t *temp_pool, 687 ap_directive_t **conftree); 688 689/** 690 * Walk a config tree and setup the server's internal structures 691 * @param conftree The config tree to walk 692 * @param parms The cmd_parms to pass to all functions 693 * @param section_vector The per-section config vector. 694 * @return Error string on error, NULL otherwise 695 */ 696AP_DECLARE(const char *) ap_walk_config(ap_directive_t *conftree, 697 cmd_parms *parms, 698 ap_conf_vector_t *section_vector); 699 700/** 701 * @defgroup ap_check_cmd_context Check command context 702 * @{ 703 */ 704/** 705 * Check the context a command is used in. 706 * @param cmd The command to check 707 * @param forbidden Where the command is forbidden. 708 * @return Error string on error, NULL on success 709 */ 710AP_DECLARE(const char *) ap_check_cmd_context(cmd_parms *cmd, 711 unsigned forbidden); 712 713#define NOT_IN_VIRTUALHOST 0x01 /**< Forbidden in <Virtualhost> */ 714#define NOT_IN_LIMIT 0x02 /**< Forbidden in <Limit> */ 715#define NOT_IN_DIRECTORY 0x04 /**< Forbidden in <Directory> */ 716#define NOT_IN_LOCATION 0x08 /**< Forbidden in <Location> */ 717#define NOT_IN_FILES 0x10 /**< Forbidden in <Files> */ 718/** Forbidden in <Directory>/<Location>/<Files>*/ 719#define NOT_IN_DIR_LOC_FILE (NOT_IN_DIRECTORY|NOT_IN_LOCATION|NOT_IN_FILES) 720/** Forbidden in <VirtualHost>/<Limit>/<Directory>/<Location>/<Files> */ 721#define GLOBAL_ONLY (NOT_IN_VIRTUALHOST|NOT_IN_LIMIT|NOT_IN_DIR_LOC_FILE) 722 723/** @} */ 724 725#ifdef CORE_PRIVATE 726 727/** 728 * @brief This structure is used to assign symbol names to module pointers 729 */ 730typedef struct { 731 const char *name; 732 module *modp; 733} ap_module_symbol_t; 734 735/** 736 * The topmost module in the list 737 * @defvar module *ap_top_module 738 */ 739AP_DECLARE_DATA extern module *ap_top_module; 740 741/** 742 * Array of all statically linked modules 743 * @defvar module *ap_prelinked_modules[] 744 */ 745AP_DECLARE_DATA extern module *ap_prelinked_modules[]; 746/** 747 * Array of all statically linked modulenames (symbols) 748 * @defvar ap_module_symbol_t ap_prelinked_modulenames[] 749 */ 750AP_DECLARE_DATA extern ap_module_symbol_t ap_prelinked_module_symbols[]; 751/** 752 * Array of all preloaded modules 753 * @defvar module *ap_preloaded_modules[] 754 */ 755AP_DECLARE_DATA extern module *ap_preloaded_modules[]; 756/** 757 * Array of all loaded modules 758 * @defvar module **ap_loaded_modules 759 */ 760AP_DECLARE_DATA extern module **ap_loaded_modules; 761 762/* For mod_so.c... */ 763/** Run a single module's two create_config hooks 764 * @param p the pool to allocate from 765 * @param s The server to configure for. 766 * @param m The module to configure 767 */ 768AP_DECLARE(void) ap_single_module_configure(apr_pool_t *p, server_rec *s, 769 module *m); 770 771/* For http_main.c... */ 772/** 773 * Add all of the prelinked modules into the loaded module list 774 * @param process The process that is currently running the server 775 */ 776AP_DECLARE(const char *) ap_setup_prelinked_modules(process_rec *process); 777 778/** 779 * Show the preloaded configuration directives, the help string explaining 780 * the directive arguments, in what module they are handled, and in 781 * what parts of the configuration they are allowed. Used for httpd -h. 782 */ 783AP_DECLARE(void) ap_show_directives(void); 784 785/** 786 * Show the preloaded module names. Used for httpd -l. 787 */ 788AP_DECLARE(void) ap_show_modules(void); 789 790/** 791 * Show the MPM name. Used in reporting modules such as mod_info to 792 * provide extra information to the user 793 */ 794AP_DECLARE(const char *) ap_show_mpm(void); 795 796/** 797 * Read all config files and setup the server 798 * @param process The process running the server 799 * @param temp_pool A pool to allocate temporary data from. 800 * @param config_name The name of the config file 801 * @param conftree Place to store the root of the config tree 802 * @return The setup server_rec list. 803 */ 804AP_DECLARE(server_rec *) ap_read_config(process_rec *process, 805 apr_pool_t *temp_pool, 806 const char *config_name, 807 ap_directive_t **conftree); 808 809/** 810 * Run all rewrite args hooks for loaded modules 811 * @param process The process currently running the server 812 */ 813AP_DECLARE(void) ap_run_rewrite_args(process_rec *process); 814 815/** 816 * Run the register hooks function for a specified module 817 * @param m The module to run the register hooks function fo 818 * @param p The pool valid for the lifetime of the module 819 */ 820AP_DECLARE(void) ap_register_hooks(module *m, apr_pool_t *p); 821 822/** 823 * Setup all virtual hosts 824 * @param p The pool to allocate from 825 * @param main_server The head of the server_rec list 826 */ 827AP_DECLARE(void) ap_fixup_virtual_hosts(apr_pool_t *p, 828 server_rec *main_server); 829 830/* For http_request.c... */ 831 832/** 833 * Setup the config vector for a request_rec 834 * @param p The pool to allocate the config vector from 835 * @return The config vector 836 */ 837AP_CORE_DECLARE(ap_conf_vector_t*) ap_create_request_config(apr_pool_t *p); 838 839/** 840 * Setup the config vector for per dir module configs 841 * @param p The pool to allocate the config vector from 842 * @return The config vector 843 */ 844AP_CORE_DECLARE(ap_conf_vector_t *) ap_create_per_dir_config(apr_pool_t *p); 845 846/** 847 * Run all of the modules merge per dir config functions 848 * @param p The pool to pass to the merge functions 849 * @param base The base directory config structure 850 * @param new_conf The new directory config structure 851 */ 852AP_CORE_DECLARE(ap_conf_vector_t*) ap_merge_per_dir_configs(apr_pool_t *p, 853 ap_conf_vector_t *base, 854 ap_conf_vector_t *new_conf); 855 856/* For http_connection.c... */ 857/** 858 * Setup the config vector for a connection_rec 859 * @param p The pool to allocate the config vector from 860 * @return The config vector 861 */ 862AP_CORE_DECLARE(ap_conf_vector_t*) ap_create_conn_config(apr_pool_t *p); 863 864/* For http_core.c... (<Directory> command and virtual hosts) */ 865 866/** 867 * parse an htaccess file 868 * @param resulting htaccess_result 869 * @param r The request currently being served 870 * @param override Which overrides are active 871 * @param path The path to the htaccess file 872 * @param access_name The list of possible names for .htaccess files 873 * int The status of the current request 874 */ 875AP_CORE_DECLARE(int) ap_parse_htaccess(ap_conf_vector_t **result, 876 request_rec *r, int override, 877 int override_opts, 878 const char *path, 879 const char *access_name); 880 881/** 882 * Setup a virtual host 883 * @param p The pool to allocate all memory from 884 * @param hostname The hostname of the virtual hsot 885 * @param main_server The main server for this Apache configuration 886 * @param ps Place to store the new server_rec 887 * return Error string on error, NULL on success 888 */ 889AP_CORE_DECLARE(const char *) ap_init_virtual_host(apr_pool_t *p, 890 const char *hostname, 891 server_rec *main_server, 892 server_rec **ps); 893 894/** 895 * Process the config file for Apache 896 * @param s The server rec to use for the command parms 897 * @param fname The name of the config file 898 * @param conftree The root node of the created config tree 899 * @param p Pool for general allocation 900 * @param ptem Pool for temporary allocation 901 */ 902AP_DECLARE(const char *) ap_process_resource_config(server_rec *s, 903 const char *fname, 904 ap_directive_t **conftree, 905 apr_pool_t *p, 906 apr_pool_t *ptemp); 907 908/** 909 * Process all directives in the config tree 910 * @param s The server rec to use in the command parms 911 * @param conftree The config tree to process 912 * @param p The pool for general allocation 913 * @param ptemp The pool for temporary allocations 914 * @return OK if no problems 915 */ 916AP_DECLARE(int) ap_process_config_tree(server_rec *s, 917 ap_directive_t *conftree, 918 apr_pool_t *p, 919 apr_pool_t *ptemp); 920 921/* Module-method dispatchers, also for http_request.c */ 922/** 923 * Run the handler phase of each module until a module accepts the 924 * responsibility of serving the request 925 * @param r The current request 926 * @return The status of the current request 927 */ 928AP_CORE_DECLARE(int) ap_invoke_handler(request_rec *r); 929 930/* for mod_perl */ 931 932/** 933 * Find a given directive in a command_rec table 934 * @param name The directive to search for 935 * @param cmds The table to search 936 * @return The directive definition of the specified directive 937 */ 938AP_CORE_DECLARE(const command_rec *) ap_find_command(const char *name, 939 const command_rec *cmds); 940 941/** 942 * Find a given directive in a list module 943 * @param cmd_name The directive to search for 944 * @param mod The module list to search 945 * @return The directive definition of the specified directive 946 */ 947AP_CORE_DECLARE(const command_rec *) ap_find_command_in_modules(const char *cmd_name, 948 module **mod); 949 950/** 951 * Ask a module to create per-server and per-section (dir/loc/file) configs 952 * (if it hasn't happened already). The results are stored in the server's 953 * config, and the specified per-section config vector. 954 * @param server The server to operate upon. 955 * @param section_vector The per-section config vector. 956 * @param section Which section to create a config for. 957 * @param mod The module which is defining the config data. 958 * @param pconf A pool for all configuration allocations. 959 * @return The (new) per-section config data. 960 */ 961AP_CORE_DECLARE(void *) ap_set_config_vectors(server_rec *server, 962 ap_conf_vector_t *section_vector, 963 const char *section, 964 module *mod, apr_pool_t *pconf); 965 966#endif 967 968 /* Hooks */ 969 970/** 971 * Run the header parser functions for each module 972 * @param r The current request 973 * @return OK or DECLINED 974 */ 975AP_DECLARE_HOOK(int,header_parser,(request_rec *r)) 976 977/** 978 * Run the pre_config function for each module 979 * @param pconf The config pool 980 * @param plog The logging streams pool 981 * @param ptemp The temporary pool 982 * @return OK or DECLINED on success anything else is a error 983 */ 984AP_DECLARE_HOOK(int,pre_config,(apr_pool_t *pconf,apr_pool_t *plog, 985 apr_pool_t *ptemp)) 986 987/** 988 * Run the test_config function for each module; this hook is run 989 * only if the server was invoked to test the configuration syntax. 990 * @param pconf The config pool 991 * @param s The list of server_recs 992 */ 993AP_DECLARE_HOOK(void,test_config,(apr_pool_t *pconf, server_rec *s)) 994 995/** 996 * Run the post_config function for each module 997 * @param pconf The config pool 998 * @param plog The logging streams pool 999 * @param ptemp The temporary pool 1000 * @param s The list of server_recs 1001 * @return OK or DECLINED on success anything else is a error 1002 */ 1003AP_DECLARE_HOOK(int,post_config,(apr_pool_t *pconf,apr_pool_t *plog, 1004 apr_pool_t *ptemp,server_rec *s)) 1005 1006/** 1007 * Run the open_logs functions for each module 1008 * @param pconf The config pool 1009 * @param plog The logging streams pool 1010 * @param ptemp The temporary pool 1011 * @param s The list of server_recs 1012 * @return OK or DECLINED on success anything else is a error 1013 */ 1014AP_DECLARE_HOOK(int,open_logs,(apr_pool_t *pconf,apr_pool_t *plog, 1015 apr_pool_t *ptemp,server_rec *s)) 1016 1017/** 1018 * Run the child_init functions for each module 1019 * @param pchild The child pool 1020 * @param s The list of server_recs in this server 1021 */ 1022AP_DECLARE_HOOK(void,child_init,(apr_pool_t *pchild, server_rec *s)) 1023 1024/** 1025 * Run the handler functions for each module 1026 * @param r The request_rec 1027 * @remark non-wildcard handlers should HOOK_MIDDLE, wildcard HOOK_LAST 1028 */ 1029AP_DECLARE_HOOK(int,handler,(request_rec *r)) 1030 1031/** 1032 * Run the quick handler functions for each module. The quick_handler 1033 * is run before any other requests hooks are called (location_walk, 1034 * directory_walk, access checking, et. al.). This hook was added 1035 * to provide a quick way to serve content from a URI keyed cache. 1036 * 1037 * @param r The request_rec 1038 * @param lookup_uri Controls whether the caller actually wants content or not. 1039 * lookup is set when the quick_handler is called out of 1040 * ap_sub_req_lookup_uri() 1041 */ 1042AP_DECLARE_HOOK(int,quick_handler,(request_rec *r, int lookup_uri)) 1043 1044/** 1045 * Retrieve the optional functions for each module. 1046 * This is run immediately before the server starts. Optional functions should 1047 * be registered during the hook registration phase. 1048 */ 1049AP_DECLARE_HOOK(void,optional_fn_retrieve,(void)) 1050 1051#ifdef __cplusplus 1052} 1053#endif 1054 1055#endif /* !APACHE_HTTP_CONFIG_H */ 1056/** @} */ 1057