Commit | Line | Data |
---|---|---|
805e021f CE |
1 | /* ==================================================================== |
2 | * Copyright (c) 1995-1998 The Apache Group. All rights reserved. | |
3 | * | |
4 | * Redistribution and use in source and binary forms, with or without | |
5 | * modification, are permitted provided that the following conditions | |
6 | * are met: | |
7 | * | |
8 | * 1. Redistributions of source code must retain the above copyright | |
9 | * notice, this list of conditions and the following disclaimer. | |
10 | * | |
11 | * 2. Redistributions in binary form must reproduce the above copyright | |
12 | * notice, this list of conditions and the following disclaimer in | |
13 | * the documentation and/or other materials provided with the | |
14 | * distribution. | |
15 | * | |
16 | * 3. All advertising materials mentioning features or use of this | |
17 | * software must display the following acknowledgment: | |
18 | * "This product includes software developed by the Apache Group | |
19 | * for use in the Apache HTTP server project (http://www.apache.org/)." | |
20 | * | |
21 | * 4. The names "Apache Server" and "Apache Group" must not be used to | |
22 | * endorse or promote products derived from this software without | |
23 | * prior written permission. For written permission, please contact | |
24 | * apache@apache.org. | |
25 | * | |
26 | * 5. Products derived from this software may not be called "Apache" | |
27 | * nor may "Apache" appear in their names without prior written | |
28 | * permission of the Apache Group. | |
29 | * | |
30 | * 6. Redistributions of any form whatsoever must retain the following | |
31 | * acknowledgment: | |
32 | * "This product includes software developed by the Apache Group | |
33 | * for use in the Apache HTTP server project (http://www.apache.org/)." | |
34 | * | |
35 | * THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY | |
36 | * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
37 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | |
38 | * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR | |
39 | * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
40 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT | |
41 | * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | |
42 | * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
43 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | |
44 | * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
45 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | |
46 | * OF THE POSSIBILITY OF SUCH DAMAGE. | |
47 | * ==================================================================== | |
48 | * | |
49 | * This software consists of voluntary contributions made by many | |
50 | * individuals on behalf of the Apache Group and was originally based | |
51 | * on public domain software written at the National Center for | |
52 | * Supercomputing Applications, University of Illinois, Urbana-Champaign. | |
53 | * For more information on the Apache Group and the Apache HTTP server | |
54 | * project, please see <http://www.apache.org/>. | |
55 | * | |
56 | */ | |
57 | ||
58 | #ifndef APACHE_ALLOC_H | |
59 | #define APACHE_ALLOC_H | |
60 | ||
61 | #ifdef __cplusplus | |
62 | extern "C" { | |
63 | #endif | |
64 | ||
65 | /* | |
66 | * Resource allocation routines... | |
67 | * | |
68 | * designed so that we don't have to keep track of EVERYTHING so that | |
69 | * it can be explicitly freed later (a fundamentally unsound strategy --- | |
70 | * particularly in the presence of die()). | |
71 | * | |
72 | * Instead, we maintain pools, and allocate items (both memory and I/O | |
73 | * handlers) from the pools --- currently there are two, one for per | |
74 | * transaction info, and one for config info. When a transaction is over, | |
75 | * we can delete everything in the per-transaction pool without fear, and | |
76 | * without thinking too hard about it either. | |
77 | * | |
78 | * rst | |
79 | */ | |
80 | ||
81 | /* Arenas for configuration info and transaction info | |
82 | * --- actual layout of the pool structure is private to | |
83 | * alloc.c. | |
84 | */ | |
85 | ||
86 | /* Need declaration of DIR on Win32 */ | |
87 | #ifdef WIN32 | |
88 | #include "os/win32/readdir.h" | |
89 | #endif | |
90 | ||
91 | typedef struct pool pool; | |
92 | typedef struct pool ap_pool; | |
93 | ||
94 | pool *ap_init_alloc(void); /* Set up everything */ | |
95 | API_EXPORT(pool *) ap_make_sub_pool(pool *); /* All pools are subpools of permanent_pool */ | |
96 | API_EXPORT(void) ap_destroy_pool(pool *); | |
97 | ||
98 | /* used to guarantee to the pool debugging code that the sub pool will not be | |
99 | * destroyed before the parent pool | |
100 | */ | |
101 | #ifndef POOL_DEBUG | |
102 | #ifdef ap_pool_join | |
103 | #undef ap_pool_join | |
104 | #endif | |
105 | #define ap_pool_join(a,b) | |
106 | #else | |
107 | API_EXPORT(void) ap_pool_join(pool * p, pool * sub); | |
108 | API_EXPORT(pool *) ap_find_pool(const void *ts); | |
109 | API_EXPORT(int) ap_pool_is_ancestor(pool * a, pool * b); | |
110 | #endif | |
111 | ||
112 | /* Clearing out EVERYTHING in an pool... destroys any sub-pools */ | |
113 | ||
114 | API_EXPORT(void) ap_clear_pool(struct pool *); | |
115 | ||
116 | /* Preparing for exec() --- close files, etc., but *don't* flush I/O | |
117 | * buffers, *don't* wait for subprocesses, and *don't* free any memory. | |
118 | */ | |
119 | ||
120 | API_EXPORT(void) ap_cleanup_for_exec(void); | |
121 | ||
122 | /* routines to allocate memory from an pool... */ | |
123 | ||
124 | API_EXPORT(void *) ap_palloc(struct pool *, int nbytes); | |
125 | API_EXPORT(void *) ap_pcalloc(struct pool *, int nbytes); | |
126 | API_EXPORT(char *) ap_pstrdup(struct pool *, const char *s); | |
127 | /* make a nul terminated copy of the n characters starting with s */ | |
128 | API_EXPORT(char *) ap_pstrndup(struct pool *, const char *s, int n); | |
129 | API_EXPORT_NONSTD(char *) ap_pstrcat(struct pool *, ...); /* all '...' must be char* */ | |
130 | API_EXPORT_NONSTD(char *) ap_psprintf(struct pool *, const char *fmt, | |
131 | ...) | |
132 | __attribute__ ((format(printf, 2, 3))); | |
133 | API_EXPORT(char *) ap_pvsprintf(struct pool *, const char *fmt, | |
134 | va_list); | |
135 | ||
136 | /* array and alist management... keeping lists of things. | |
137 | * Common enough to want common support code ... | |
138 | */ | |
139 | ||
140 | typedef struct { | |
141 | ap_pool *pool; | |
142 | int elt_size; | |
143 | int nelts; | |
144 | int nalloc; | |
145 | char *elts; | |
146 | } array_header; | |
147 | ||
148 | API_EXPORT(array_header *) ap_make_array(pool * p, int nelts, | |
149 | int elt_size); | |
150 | API_EXPORT(void *) ap_push_array(array_header *); | |
151 | API_EXPORT(void) ap_array_cat(array_header * dst, | |
152 | const array_header * src); | |
153 | API_EXPORT(array_header *) ap_append_arrays(pool *, | |
154 | const array_header *, | |
155 | const array_header *); | |
156 | ||
157 | /* copy_array copies the *entire* array. copy_array_hdr just copies | |
158 | * the header, and arranges for the elements to be copied if (and only | |
159 | * if) the code subsequently does a push or arraycat. | |
160 | */ | |
161 | ||
162 | API_EXPORT(array_header *) ap_copy_array(pool * p, | |
163 | const array_header * src); | |
164 | API_EXPORT(array_header *) ap_copy_array_hdr(pool * p, | |
165 | const array_header * src); | |
166 | ||
167 | ||
168 | /* Tables. Implemented alist style, for now, though we try to keep | |
169 | * it so that imposing a hash table structure on top in the future | |
170 | * wouldn't be *too* hard... | |
171 | * | |
172 | * Note that key comparisons for these are case-insensitive, largely | |
173 | * because that's what's appropriate and convenient everywhere they're | |
174 | * currently being used... | |
175 | */ | |
176 | ||
177 | typedef struct table table; | |
178 | ||
179 | typedef struct { | |
180 | char *key; /* maybe NULL in future; | |
181 | * check when iterating thru table_elts | |
182 | */ | |
183 | char *val; | |
184 | } table_entry; | |
185 | ||
186 | API_EXPORT(table *) ap_make_table(pool * p, int nelts); | |
187 | API_EXPORT(table *) ap_copy_table(pool * p, const table *); | |
188 | API_EXPORT(void) ap_clear_table(table *); | |
189 | API_EXPORT(const char *) ap_table_get(const table *, const char *); | |
190 | API_EXPORT(void) ap_table_set(table *, const char *name, | |
191 | const char *val); | |
192 | API_EXPORT(void) ap_table_setn(table *, const char *name, | |
193 | const char *val); | |
194 | API_EXPORT(void) ap_table_merge(table *, const char *name, | |
195 | const char *more_val); | |
196 | API_EXPORT(void) ap_table_mergen(table *, const char *name, | |
197 | const char *more_val); | |
198 | API_EXPORT(void) ap_table_unset(table *, const char *key); | |
199 | API_EXPORT(void) ap_table_add(table *, const char *name, | |
200 | const char *val); | |
201 | API_EXPORT(void) ap_table_addn(table *, const char *name, | |
202 | const char *val); | |
203 | API_EXPORT(void) | |
204 | ap_table_do(int (*comp) (void *, const char *, const char *), void *rec, | |
205 | const table * t, ...); | |
206 | ||
207 | API_EXPORT(table *) ap_overlay_tables(pool * p, const table * overlay, | |
208 | const table * base); | |
209 | ||
210 | /* XXX: these know about the definition of struct table in alloc.c. That | |
211 | * definition is not here because it is supposed to be private, and by not | |
212 | * placing it here we are able to get compile-time diagnostics from modules | |
213 | * written which assume that a table is the same as an array_header. -djg | |
214 | */ | |
215 | #define ap_table_elts(t) ((array_header *)(t)) | |
216 | #define ap_is_empty_table(t) (((t) == NULL)||(((array_header *)(t))->nelts == 0)) | |
217 | ||
218 | /* routines to remember allocation of other sorts of things... | |
219 | * generic interface first. Note that we want to have two separate | |
220 | * cleanup functions in the general case, one for exec() preparation, | |
221 | * to keep CGI scripts and the like from inheriting access to things | |
222 | * they shouldn't be able to touch, and one for actually cleaning up, | |
223 | * when the actual server process wants to get rid of the thing, | |
224 | * whatever it is. | |
225 | * | |
226 | * kill_cleanup disarms a cleanup, presumably because the resource in | |
227 | * question has been closed, freed, or whatever, and it's scarce | |
228 | * enough to want to reclaim (e.g., descriptors). It arranges for the | |
229 | * resource not to be cleaned up a second time (it might have been | |
230 | * reallocated). run_cleanup does the same, but runs it first. | |
231 | * | |
232 | * Cleanups are identified for purposes of finding & running them off by the | |
233 | * plain_cleanup and data, which should presumably be unique. | |
234 | * | |
235 | * NB any code which invokes register_cleanup or kill_cleanup directly | |
236 | * is a critical section which should be guarded by block_alarms() and | |
237 | * unblock_alarms() below... | |
238 | */ | |
239 | ||
240 | API_EXPORT(void) ap_register_cleanup(pool * p, void *data, | |
241 | void (*plain_cleanup) (void *), | |
242 | void (*child_cleanup) (void *)); | |
243 | ||
244 | API_EXPORT(void) ap_kill_cleanup(pool * p, void *data, | |
245 | void (*plain_cleanup) (void *)); | |
246 | API_EXPORT(void) ap_run_cleanup(pool * p, void *data, | |
247 | void (*cleanup) (void *)); | |
248 | ||
249 | /* A "do-nothing" cleanup, for register_cleanup; it's faster to do | |
250 | * things this way than to test for NULL. */ | |
251 | API_EXPORT_NONSTD(void) ap_null_cleanup(void *data); | |
252 | ||
253 | /* The time between when a resource is actually allocated, and when it | |
254 | * its cleanup is registered is a critical section, during which the | |
255 | * resource could leak if we got interrupted or timed out. So, anything | |
256 | * which registers cleanups should bracket resource allocation and the | |
257 | * cleanup registry with these. (This is done internally by run_cleanup). | |
258 | * | |
259 | * NB they are actually implemented in http_main.c, since they are bound | |
260 | * up with timeout handling in general... | |
261 | */ | |
262 | ||
263 | API_EXPORT(void) ap_block_alarms(void); | |
264 | API_EXPORT(void) ap_unblock_alarms(void); | |
265 | ||
266 | /* Common cases which want utility support.. | |
267 | * the note_cleanups_for_foo routines are for | |
268 | */ | |
269 | ||
270 | API_EXPORT(FILE *) ap_pfopen(struct pool *, const char *name, | |
271 | const char *fmode); | |
272 | API_EXPORT(FILE *) ap_pfdopen(struct pool *, int fd, const char *fmode); | |
273 | API_EXPORT(int) ap_popenf(struct pool *, const char *name, int flg, | |
274 | int mode); | |
275 | ||
276 | API_EXPORT(void) ap_note_cleanups_for_file(pool *, FILE *); | |
277 | API_EXPORT(void) ap_note_cleanups_for_fd(pool *, int); | |
278 | #ifdef WIN32 | |
279 | API_EXPORT(void) ap_note_cleanups_for_h(pool *, HANDLE); | |
280 | #endif | |
281 | API_EXPORT(void) ap_kill_cleanups_for_fd(pool * p, int fd); | |
282 | ||
283 | API_EXPORT(void) ap_note_cleanups_for_socket(pool *, int); | |
284 | API_EXPORT(void) ap_kill_cleanups_for_socket(pool * p, int sock); | |
285 | API_EXPORT(int) ap_psocket(pool * p, int, int, int); | |
286 | API_EXPORT(int) ap_pclosesocket(pool * a, int sock); | |
287 | ||
288 | API_EXPORT(regex_t *) ap_pregcomp(pool * p, const char *pattern, | |
289 | int cflags); | |
290 | API_EXPORT(void) ap_pregfree(pool * p, regex_t * reg); | |
291 | ||
292 | /* routines to note closes... file descriptors are constrained enough | |
293 | * on some systems that we want to support this. | |
294 | */ | |
295 | ||
296 | API_EXPORT(int) ap_pfclose(struct pool *, FILE *); | |
297 | API_EXPORT(int) ap_pclosef(struct pool *, int fd); | |
298 | #ifdef WIN32 | |
299 | API_EXPORT(int) ap_pcloseh(struct pool *, HANDLE hDevice); | |
300 | #endif | |
301 | ||
302 | /* routines to deal with directories */ | |
303 | API_EXPORT(DIR *) ap_popendir(pool * p, const char *name); | |
304 | API_EXPORT(void) ap_pclosedir(pool * p, DIR * d); | |
305 | ||
306 | /* ... even child processes (which we may want to wait for, | |
307 | * or to kill outright, on unexpected termination). | |
308 | * | |
309 | * ap_spawn_child is a utility routine which handles an awful lot of | |
310 | * the rigamarole associated with spawning a child --- it arranges | |
311 | * for pipes to the child's stdin and stdout, if desired (if not, | |
312 | * set the associated args to NULL). It takes as args a function | |
313 | * to call in the child, and an argument to be passed to the function. | |
314 | */ | |
315 | ||
316 | enum kill_conditions { | |
317 | kill_never, /* process is never sent any signals */ | |
318 | kill_always, /* process is sent SIGKILL on pool cleanup */ | |
319 | kill_after_timeout, /* SIGTERM, wait 3 seconds, SIGKILL */ | |
320 | just_wait, /* wait forever for the process to complete */ | |
321 | kill_only_once /* send SIGTERM and then wait */ | |
322 | }; | |
323 | ||
324 | typedef struct child_info child_info; | |
325 | API_EXPORT(void) ap_note_subprocess(pool * a, int pid, | |
326 | enum kill_conditions how); | |
327 | API_EXPORT(int) ap_spawn_child(pool *, int (*)(void *, child_info *), | |
328 | void *, enum kill_conditions, | |
329 | FILE ** pipe_in, FILE ** pipe_out, | |
330 | FILE ** pipe_err); | |
331 | ||
332 | /* magic numbers --- min free bytes to consider a free pool block useable, | |
333 | * and the min amount to allocate if we have to go to malloc() */ | |
334 | ||
335 | #ifndef BLOCK_MINFREE | |
336 | #define BLOCK_MINFREE 4096 | |
337 | #endif | |
338 | #ifndef BLOCK_MINALLOC | |
339 | #define BLOCK_MINALLOC 8192 | |
340 | #endif | |
341 | ||
342 | /* Finally, some accounting */ | |
343 | ||
344 | API_EXPORT(long) ap_bytes_in_pool(pool * p); | |
345 | API_EXPORT(long) ap_bytes_in_free_blocks(void); | |
346 | ||
347 | #ifdef __cplusplus | |
348 | } | |
349 | #endif | |
350 | #endif /* !APACHE_ALLOC_H */ |