Commit | Line | Data |
---|---|---|
805e021f CE |
1 | /* ==================================================================== |
2 | * Copyright (c) 1995-1999 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 | /* ap_array_pstrcat generates a new string from the pool containing | |
158 | * the concatenated sequence of substrings referenced as elements within | |
159 | * the array. The string will be empty if all substrings are empty or null, | |
160 | * or if there are no elements in the array. | |
161 | * If sep is non-NUL, it will be inserted between elements as a separator. | |
162 | */ | |
163 | API_EXPORT(char *) ap_array_pstrcat(pool * p, const array_header * arr, | |
164 | const char sep); | |
165 | ||
166 | /* copy_array copies the *entire* array. copy_array_hdr just copies | |
167 | * the header, and arranges for the elements to be copied if (and only | |
168 | * if) the code subsequently does a push or arraycat. | |
169 | */ | |
170 | ||
171 | API_EXPORT(array_header *) ap_copy_array(pool * p, | |
172 | const array_header * src); | |
173 | API_EXPORT(array_header *) ap_copy_array_hdr(pool * p, | |
174 | const array_header * src); | |
175 | ||
176 | ||
177 | /* Tables. Implemented alist style, for now, though we try to keep | |
178 | * it so that imposing a hash table structure on top in the future | |
179 | * wouldn't be *too* hard... | |
180 | * | |
181 | * Note that key comparisons for these are case-insensitive, largely | |
182 | * because that's what's appropriate and convenient everywhere they're | |
183 | * currently being used... | |
184 | */ | |
185 | ||
186 | typedef struct table table; | |
187 | ||
188 | typedef struct { | |
189 | char *key; /* maybe NULL in future; | |
190 | * check when iterating thru table_elts | |
191 | */ | |
192 | char *val; | |
193 | } table_entry; | |
194 | ||
195 | API_EXPORT(table *) ap_make_table(pool * p, int nelts); | |
196 | API_EXPORT(table *) ap_copy_table(pool * p, const table *); | |
197 | API_EXPORT(void) ap_clear_table(table *); | |
198 | API_EXPORT(const char *) ap_table_get(const table *, const char *); | |
199 | API_EXPORT(void) ap_table_set(table *, const char *name, | |
200 | const char *val); | |
201 | API_EXPORT(void) ap_table_setn(table *, const char *name, | |
202 | const char *val); | |
203 | API_EXPORT(void) ap_table_merge(table *, const char *name, | |
204 | const char *more_val); | |
205 | API_EXPORT(void) ap_table_mergen(table *, const char *name, | |
206 | const char *more_val); | |
207 | API_EXPORT(void) ap_table_unset(table *, const char *key); | |
208 | API_EXPORT(void) ap_table_add(table *, const char *name, | |
209 | const char *val); | |
210 | API_EXPORT(void) ap_table_addn(table *, const char *name, | |
211 | const char *val); | |
212 | API_EXPORT(void) | |
213 | ap_table_do(int (*comp) (void *, const char *, const char *), void *rec, | |
214 | const table * t, ...); | |
215 | ||
216 | API_EXPORT(table *) ap_overlay_tables(pool * p, const table * overlay, | |
217 | const table * base); | |
218 | ||
219 | /* Conceptually, ap_overlap_tables does this: | |
220 | ||
221 | array_header *barr = ap_table_elts(b); | |
222 | table_entry *belt = (table_entry *)barr->elts; | |
223 | int i; | |
224 | ||
225 | for (i = 0; i < barr->nelts; ++i) { | |
226 | if (flags & AP_OVERLAP_TABLES_MERGE) { | |
227 | ap_table_mergen(a, belt[i].key, belt[i].val); | |
228 | } | |
229 | else { | |
230 | ap_table_setn(a, belt[i].key, belt[i].val); | |
231 | } | |
232 | } | |
233 | ||
234 | Except that it is more efficient (less space and cpu-time) especially | |
235 | when b has many elements. | |
236 | ||
237 | Notice the assumptions on the keys and values in b -- they must be | |
238 | in an ancestor of a's pool. In practice b and a are usually from | |
239 | the same pool. | |
240 | */ | |
241 | #define AP_OVERLAP_TABLES_SET (0) | |
242 | #define AP_OVERLAP_TABLES_MERGE (1) | |
243 | API_EXPORT(void) ap_overlap_tables(table * a, const table * b, | |
244 | unsigned flags); | |
245 | ||
246 | /* XXX: these know about the definition of struct table in alloc.c. That | |
247 | * definition is not here because it is supposed to be private, and by not | |
248 | * placing it here we are able to get compile-time diagnostics from modules | |
249 | * written which assume that a table is the same as an array_header. -djg | |
250 | */ | |
251 | #define ap_table_elts(t) ((array_header *)(t)) | |
252 | #define ap_is_empty_table(t) (((t) == NULL)||(((array_header *)(t))->nelts == 0)) | |
253 | ||
254 | /* routines to remember allocation of other sorts of things... | |
255 | * generic interface first. Note that we want to have two separate | |
256 | * cleanup functions in the general case, one for exec() preparation, | |
257 | * to keep CGI scripts and the like from inheriting access to things | |
258 | * they shouldn't be able to touch, and one for actually cleaning up, | |
259 | * when the actual server process wants to get rid of the thing, | |
260 | * whatever it is. | |
261 | * | |
262 | * kill_cleanup disarms a cleanup, presumably because the resource in | |
263 | * question has been closed, freed, or whatever, and it's scarce | |
264 | * enough to want to reclaim (e.g., descriptors). It arranges for the | |
265 | * resource not to be cleaned up a second time (it might have been | |
266 | * reallocated). run_cleanup does the same, but runs it first. | |
267 | * | |
268 | * Cleanups are identified for purposes of finding & running them off by the | |
269 | * plain_cleanup and data, which should presumably be unique. | |
270 | * | |
271 | * NB any code which invokes register_cleanup or kill_cleanup directly | |
272 | * is a critical section which should be guarded by block_alarms() and | |
273 | * unblock_alarms() below... | |
274 | */ | |
275 | ||
276 | API_EXPORT(void) ap_register_cleanup(pool * p, void *data, | |
277 | void (*plain_cleanup) (void *), | |
278 | void (*child_cleanup) (void *)); | |
279 | ||
280 | API_EXPORT(void) ap_kill_cleanup(pool * p, void *data, | |
281 | void (*plain_cleanup) (void *)); | |
282 | API_EXPORT(void) ap_run_cleanup(pool * p, void *data, | |
283 | void (*cleanup) (void *)); | |
284 | ||
285 | /* A "do-nothing" cleanup, for register_cleanup; it's faster to do | |
286 | * things this way than to test for NULL. */ | |
287 | API_EXPORT_NONSTD(void) ap_null_cleanup(void *data); | |
288 | ||
289 | /* The time between when a resource is actually allocated, and when it | |
290 | * its cleanup is registered is a critical section, during which the | |
291 | * resource could leak if we got interrupted or timed out. So, anything | |
292 | * which registers cleanups should bracket resource allocation and the | |
293 | * cleanup registry with these. (This is done internally by run_cleanup). | |
294 | * | |
295 | * NB they are actually implemented in http_main.c, since they are bound | |
296 | * up with timeout handling in general... | |
297 | */ | |
298 | ||
299 | #ifdef TPF | |
300 | #define ap_block_alarms() (0) | |
301 | #define ap_unblock_alarms() (0) | |
302 | #else | |
303 | API_EXPORT(void) ap_block_alarms(void); | |
304 | API_EXPORT(void) ap_unblock_alarms(void); | |
305 | #endif /* TPF */ | |
306 | ||
307 | /* Common cases which want utility support.. | |
308 | * the note_cleanups_for_foo routines are for | |
309 | */ | |
310 | ||
311 | API_EXPORT(FILE *) ap_pfopen(struct pool *, const char *name, | |
312 | const char *fmode); | |
313 | API_EXPORT(FILE *) ap_pfdopen(struct pool *, int fd, const char *fmode); | |
314 | API_EXPORT(int) ap_popenf(struct pool *, const char *name, int flg, | |
315 | int mode); | |
316 | ||
317 | API_EXPORT(void) ap_note_cleanups_for_file(pool *, FILE *); | |
318 | API_EXPORT(void) ap_note_cleanups_for_fd(pool *, int); | |
319 | #ifdef WIN32 | |
320 | API_EXPORT(void) ap_note_cleanups_for_h(pool *, HANDLE); | |
321 | #endif | |
322 | API_EXPORT(void) ap_kill_cleanups_for_fd(pool * p, int fd); | |
323 | ||
324 | API_EXPORT(void) ap_note_cleanups_for_socket(pool *, int); | |
325 | API_EXPORT(void) ap_kill_cleanups_for_socket(pool * p, int sock); | |
326 | API_EXPORT(int) ap_psocket(pool * p, int, int, int); | |
327 | API_EXPORT(int) ap_pclosesocket(pool * a, int sock); | |
328 | ||
329 | API_EXPORT(regex_t *) ap_pregcomp(pool * p, const char *pattern, | |
330 | int cflags); | |
331 | API_EXPORT(void) ap_pregfree(pool * p, regex_t * reg); | |
332 | ||
333 | /* routines to note closes... file descriptors are constrained enough | |
334 | * on some systems that we want to support this. | |
335 | */ | |
336 | ||
337 | API_EXPORT(int) ap_pfclose(struct pool *, FILE *); | |
338 | API_EXPORT(int) ap_pclosef(struct pool *, int fd); | |
339 | #ifdef WIN32 | |
340 | API_EXPORT(int) ap_pcloseh(struct pool *, HANDLE hDevice); | |
341 | #endif | |
342 | ||
343 | /* routines to deal with directories */ | |
344 | API_EXPORT(DIR *) ap_popendir(pool * p, const char *name); | |
345 | API_EXPORT(void) ap_pclosedir(pool * p, DIR * d); | |
346 | ||
347 | /* ... even child processes (which we may want to wait for, | |
348 | * or to kill outright, on unexpected termination). | |
349 | * | |
350 | * ap_spawn_child is a utility routine which handles an awful lot of | |
351 | * the rigamarole associated with spawning a child --- it arranges | |
352 | * for pipes to the child's stdin and stdout, if desired (if not, | |
353 | * set the associated args to NULL). It takes as args a function | |
354 | * to call in the child, and an argument to be passed to the function. | |
355 | */ | |
356 | ||
357 | enum kill_conditions { | |
358 | kill_never, /* process is never sent any signals */ | |
359 | kill_always, /* process is sent SIGKILL on pool cleanup */ | |
360 | kill_after_timeout, /* SIGTERM, wait 3 seconds, SIGKILL */ | |
361 | just_wait, /* wait forever for the process to complete */ | |
362 | kill_only_once /* send SIGTERM and then wait */ | |
363 | }; | |
364 | ||
365 | typedef struct child_info child_info; | |
366 | API_EXPORT(void) ap_note_subprocess(pool * a, pid_t pid, | |
367 | enum kill_conditions how); | |
368 | API_EXPORT(int) ap_spawn_child(pool *, int (*)(void *, child_info *), | |
369 | void *, enum kill_conditions, | |
370 | FILE ** pipe_in, FILE ** pipe_out, | |
371 | FILE ** pipe_err); | |
372 | ||
373 | /* magic numbers --- min free bytes to consider a free pool block useable, | |
374 | * and the min amount to allocate if we have to go to malloc() */ | |
375 | ||
376 | #ifndef BLOCK_MINFREE | |
377 | #define BLOCK_MINFREE 4096 | |
378 | #endif | |
379 | #ifndef BLOCK_MINALLOC | |
380 | #define BLOCK_MINALLOC 8192 | |
381 | #endif | |
382 | ||
383 | /* Finally, some accounting */ | |
384 | ||
385 | API_EXPORT(long) ap_bytes_in_pool(pool * p); | |
386 | API_EXPORT(long) ap_bytes_in_free_blocks(void); | |
387 | ||
388 | #ifdef __cplusplus | |
389 | } | |
390 | #endif | |
391 | #endif /* !APACHE_ALLOC_H */ |