Commit | Line | Data |
---|---|---|
805e021f CE |
1 | /* ==================================================================== |
2 | * Copyright (c) 1998-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 | * The ap_vsnprintf/ap_snprintf functions are based on, and used with the | |
57 | * permission of, the SIO stdio-replacement strx_* functions by Panos | |
58 | * Tsirigotis <panos@alumni.cs.colorado.edu> for xinetd. | |
59 | */ | |
60 | ||
61 | #ifndef APACHE_AP_H | |
62 | #define APACHE_AP_H | |
63 | ||
64 | #ifdef __cplusplus | |
65 | extern "C" { | |
66 | #endif | |
67 | ||
68 | API_EXPORT(char *) ap_cpystrn(char *, const char *, size_t); | |
69 | int ap_slack(int, int); | |
70 | int ap_execle(const char *, const char *, ...); | |
71 | int ap_execve(const char *, const char *argv[], const char *envp[]); | |
72 | ||
73 | /* small utility macros to make things easier to read */ | |
74 | ||
75 | #ifdef WIN32 | |
76 | #define ap_killpg(x, y) | |
77 | #else | |
78 | #ifdef NO_KILLPG | |
79 | #define ap_killpg(x, y) (kill (-(x), (y))) | |
80 | #else | |
81 | #define ap_killpg(x, y) (killpg ((x), (y))) | |
82 | #endif | |
83 | #endif /* WIN32 */ | |
84 | ||
85 | /* ap_vformatter() is a generic printf-style formatting routine | |
86 | * with some extensions. The extensions are: | |
87 | * | |
88 | * %pA takes a struct in_addr *, and prints it as a.b.c.d | |
89 | * %pI takes a struct sockaddr_in * and prints it as a.b.c.d:port | |
90 | * %pp takes a void * and outputs it in hex | |
91 | * | |
92 | * The %p hacks are to force gcc's printf warning code to skip | |
93 | * over a pointer argument without complaining. This does | |
94 | * mean that the ANSI-style %p (output a void * in hex format) won't | |
95 | * work as expected at all, but that seems to be a fair trade-off | |
96 | * for the increased robustness of having printf-warnings work. | |
97 | * | |
98 | * Additionally, ap_vformatter allows for arbitrary output methods | |
99 | * using the ap_vformatter_buff and flush_func. | |
100 | * | |
101 | * The ap_vformatter_buff has two elements curpos and endpos. | |
102 | * curpos is where ap_vformatter will write the next byte of output. | |
103 | * It proceeds writing output to curpos, and updating curpos, until | |
104 | * either the end of output is reached, or curpos == endpos (i.e. the | |
105 | * buffer is full). | |
106 | * | |
107 | * If the end of output is reached, ap_vformatter returns the | |
108 | * number of bytes written. | |
109 | * | |
110 | * When the buffer is full, the flush_func is called. The flush_func | |
111 | * can return -1 to indicate that no further output should be attempted, | |
112 | * and ap_vformatter will return immediately with -1. Otherwise | |
113 | * the flush_func should flush the buffer in whatever manner is | |
114 | * appropriate, re-initialize curpos and endpos, and return 0. | |
115 | * | |
116 | * Note that flush_func is only invoked as a result of attempting to | |
117 | * write another byte at curpos when curpos >= endpos. So for | |
118 | * example, it's possible when the output exactly matches the buffer | |
119 | * space available that curpos == endpos will be true when | |
120 | * ap_vformatter returns. | |
121 | * | |
122 | * ap_vformatter does not call out to any other code, it is entirely | |
123 | * self-contained. This allows the callers to do things which are | |
124 | * otherwise "unsafe". For example, ap_psprintf uses the "scratch" | |
125 | * space at the unallocated end of a block, and doesn't actually | |
126 | * complete the allocation until ap_vformatter returns. ap_psprintf | |
127 | * would be completely broken if ap_vformatter were to call anything | |
128 | * that used a pool. Similarly http_bprintf() uses the "scratch" | |
129 | * space at the end of its output buffer, and doesn't actually note | |
130 | * that the space is in use until it either has to flush the buffer | |
131 | * or until ap_vformatter returns. | |
132 | */ | |
133 | ||
134 | typedef struct { | |
135 | char *curpos; | |
136 | char *endpos; | |
137 | } ap_vformatter_buff; | |
138 | ||
139 | API_EXPORT(int) ap_vformatter(int (*flush_func) (ap_vformatter_buff *), | |
140 | ap_vformatter_buff *, const char *fmt, | |
141 | va_list ap); | |
142 | ||
143 | /* These are snprintf implementations based on ap_vformatter(). | |
144 | * | |
145 | * Note that various standards and implementations disagree on the return | |
146 | * value of snprintf, and side-effects due to %n in the formatting string. | |
147 | * ap_snprintf behaves as follows: | |
148 | * | |
149 | * Process the format string until the entire string is exhausted, or | |
150 | * the buffer fills. If the buffer fills then stop processing immediately | |
151 | * (so no further %n arguments are processed), and return the buffer | |
152 | * length. In all cases the buffer is NUL terminated. | |
153 | * | |
154 | * In no event does ap_snprintf return a negative number. It's not possible | |
155 | * to distinguish between an output which was truncated, and an output which | |
156 | * exactly filled the buffer. | |
157 | */ | |
158 | API_EXPORT(int) ap_snprintf(char *buf, size_t len, const char *format, | |
159 | ...) | |
160 | __attribute__ ((format(printf, 3, 4))); | |
161 | API_EXPORT(int) ap_vsnprintf(char *buf, size_t len, const char *format, | |
162 | va_list ap); | |
163 | ||
164 | #ifdef __cplusplus | |
165 | } | |
166 | #endif | |
167 | #endif /* !APACHE_AP_H */ |