1 /* $OpenBSD: http_main.h,v 1.13 2006/03/22 13:19:19 ray Exp $ */ 2 3 /* ==================================================================== 4 * The Apache Software License, Version 1.1 5 * 6 * Copyright (c) 2000-2003 The Apache Software Foundation. All rights 7 * reserved. 8 * 9 * Redistribution and use in source and binary forms, with or without 10 * modification, are permitted provided that the following conditions 11 * are met: 12 * 13 * 1. Redistributions of source code must retain the above copyright 14 * notice, this list of conditions and the following disclaimer. 15 * 16 * 2. Redistributions in binary form must reproduce the above copyright 17 * notice, this list of conditions and the following disclaimer in 18 * the documentation and/or other materials provided with the 19 * distribution. 20 * 21 * 3. The end-user documentation included with the redistribution, 22 * if any, must include the following acknowledgment: 23 * "This product includes software developed by the 24 * Apache Software Foundation (http://www.apache.org/)." 25 * Alternately, this acknowledgment may appear in the software itself, 26 * if and wherever such third-party acknowledgments normally appear. 27 * 28 * 4. The names "Apache" and "Apache Software Foundation" must 29 * not be used to endorse or promote products derived from this 30 * software without prior written permission. For written 31 * permission, please contact apache@apache.org. 32 * 33 * 5. Products derived from this software may not be called "Apache", 34 * nor may "Apache" appear in their name, without prior written 35 * permission of the Apache Software Foundation. 36 * 37 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 39 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 40 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR 41 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 42 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 43 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 44 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 45 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 46 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 47 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 48 * SUCH DAMAGE. 49 * ==================================================================== 50 * 51 * This software consists of voluntary contributions made by many 52 * individuals on behalf of the Apache Software Foundation. For more 53 * information on the Apache Software Foundation, please see 54 * <http://www.apache.org/>. 55 * 56 * Portions of this software are based upon public domain software 57 * originally written at the National Center for Supercomputing Applications, 58 * University of Illinois, Urbana-Champaign. 59 */ 60 61 #ifndef APACHE_HTTP_MAIN_H 62 #define APACHE_HTTP_MAIN_H 63 64 #ifdef __cplusplus 65 extern "C" { 66 #endif 67 68 /* 69 * Routines in http_main.c which other code --- in particular modules --- 70 * may want to call. Right now, that's limited to timeout handling. 71 * There are two functions which modules can call to trigger a timeout 72 * (with the per-virtual-server timeout duration); these are hard_timeout 73 * and soft_timeout. 74 * 75 * The difference between the two is what happens when the timeout 76 * expires (or earlier than that, if the client connection aborts) --- 77 * a soft_timeout just puts the connection to the client in an 78 * "aborted" state, which will cause http_protocol.c to stop trying to 79 * talk to the client, but otherwise allows the code to continue normally. 80 * hard_timeout(), by contrast, logs the request, and then aborts it 81 * completely --- longjmp()ing out to the accept() loop in http_main. 82 * Any resources tied into the request's resource pool will be cleaned up; 83 * everything that isn't will leak. 84 * 85 * soft_timeout() is recommended as a general rule, because it gives your 86 * code a chance to clean up. However, hard_timeout() may be the most 87 * convenient way of dealing with timeouts waiting for some external 88 * resource other than the client, if you can live with the restrictions. 89 * 90 * (When a hard timeout is in scope, critical sections can be guarded 91 * with block_alarms() and unblock_alarms() --- these are declared in 92 * alloc.c because they are most often used in conjunction with 93 * routines to allocate something or other, to make sure that the 94 * cleanup does get registered before any alarm is allowed to happen 95 * which might require it to be cleaned up; they * are, however, 96 * implemented in http_main.c). 97 * 98 * NOTE! It's not "fair" for a hard_timeout to be in scope through calls 99 * across modules. Your module code really has no idea what other modules may 100 * be present in the server, and they may not take too kindly to having a 101 * longjmp() happen -- it could result in corrupted state. Heck they may not 102 * even take to kindly to a soft_timeout()... because it can cause EINTR to 103 * happen on pretty much any syscall, and unless all the libraries and modules 104 * in use are known to deal well with EINTR it could cause corruption as well. 105 * But things are likely to do much better with a soft_timeout in scope than a 106 * hard_timeout. 107 * 108 * A module MAY NOT use a hard_timeout() across * sub_req_lookup_xxx() 109 * functions, or across run_sub_request() functions. A module SHOULD NOT use a 110 * soft_timeout() in either of these cases, but sometimes there's just no 111 * choice. 112 * 113 * kill_timeout() will disarm either variety of timeout. 114 * 115 * reset_timeout() resets the timeout in progress. 116 */ 117 118 API_EXPORT(void) ap_start_shutdown(void); 119 API_EXPORT(void) ap_start_restart(int); 120 API_EXPORT(void) ap_hard_timeout(char *, request_rec *); 121 API_EXPORT(void) ap_keepalive_timeout(char *, request_rec *); 122 API_EXPORT(void) ap_soft_timeout(char *, request_rec *); 123 API_EXPORT(void) ap_kill_timeout(request_rec *); 124 API_EXPORT(void) ap_reset_timeout(request_rec *); 125 126 API_EXPORT(void) ap_child_terminate(request_rec *r); 127 API_EXPORT(int) ap_update_child_status(int child_num, int status, 128 request_rec *r); 129 void ap_time_process_request(int child_num, int status); 130 API_EXPORT(unsigned int) ap_set_callback_and_alarm(void (*fn) (int), int x); 131 API_EXPORT(int) ap_check_alarm(void); 132 API_EXPORT(void) ap_server_strip_chroot(char *, int); 133 API_EXPORT(int) ap_server_is_chrooted(void); 134 API_EXPORT(int) ap_server_chroot_desired(void); 135 136 void setup_signal_names(char *prefix); 137 138 /* functions for determination and setting of accept() mutexing */ 139 char *ap_default_mutex_method(void); 140 char *ap_init_mutex_method(char *t); 141 142 /* 143 * register an other_child -- a child which the main loop keeps track of 144 * and knows it is different than the rest of the scoreboard. 145 * 146 * pid is the pid of the child. 147 * 148 * maintenance is a function that is invoked with a reason, the data 149 * pointer passed here, and when appropriate a status result from waitpid(). 150 * 151 * write_fd is an fd that is probed for writing by select() if it is ever 152 * unwritable, then maintenance is invoked with reason OC_REASON_UNWRITABLE. 153 * This is useful for log pipe children, to know when they've blocked. To 154 * disable this feature, use -1 for write_fd. 155 */ 156 API_EXPORT(void) ap_register_other_child(int pid, 157 void (*maintenance) (int reason, void *data, ap_wait_t status), 158 void *data, int write_fd); 159 #define OC_REASON_DEATH 0 /* child has died, caller must call 160 * unregister still */ 161 #define OC_REASON_UNWRITABLE 1 /* write_fd is unwritable */ 162 #define OC_REASON_RESTART 2 /* a restart is occuring, perform 163 * any necessary cleanup (including 164 * sending a special signal to child) 165 */ 166 #define OC_REASON_UNREGISTER 3 /* unregister has been called, do 167 * whatever is necessary (including 168 * kill the child) */ 169 #define OC_REASON_LOST 4 /* somehow the child exited without 170 * us knowing ... buggy os? */ 171 172 /* 173 * unregister an other_child. Note that the data pointer is used here, and 174 * is assumed to be unique per other_child. This is because the pid and 175 * write_fd are possibly killed off separately. 176 */ 177 API_EXPORT(void) ap_unregister_other_child(void *data); 178 179 #ifdef __cplusplus 180 } 181 #endif 182 183 #endif /* !APACHE_HTTP_MAIN_H */ 184