granicus.if.org Git - apache/blob - include/util_script.h

   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  util_script.h
  19  * @brief Apache script tools
  20  *
  21  * @defgroup APACHE_CORE_SCRIPT Script Tools
  22  * @ingroup  APACHE_CORE
  23  * @{
  24  */
  25
  26 #ifndef APACHE_UTIL_SCRIPT_H
  27 #define APACHE_UTIL_SCRIPT_H
  28
  29 #include "apr_buckets.h"
  30 #include "ap_config.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 #ifndef APACHE_ARG_MAX
  37 #ifdef _POSIX_ARG_MAX
  38 #define APACHE_ARG_MAX _POSIX_ARG_MAX
  39 #else
  40 #define APACHE_ARG_MAX 512
  41 #endif
  42 #endif
  43
  44 /**
  45  * Create an environment variable out of an Apache table of key-value pairs
  46  * @param p pool to allocate out of
  47  * @param t Apache table of key-value pairs
  48  * @return An array containing the same key-value pairs suitable for
  49  *         use with an exec call.
  50  * @fn char **ap_create_environment(apr_pool_t *p, apr_table_t *t)
  51  */
  52 AP_DECLARE(char **) ap_create_environment(apr_pool_t *p, apr_table_t *t);
  53
  54 /**
  55  * This "cute" little function comes about because the path info on
  56  * filenames and URLs aren't always the same. So we take the two,
  57  * and find as much of the two that match as possible.
  58  * @param uri The uri we are currently parsing
  59  * @param path_info The current path info
  60  * @return The length of the path info
  61  * @fn int ap_find_path_info(const char *uri, const char *path_info)
  62  */
  63 AP_DECLARE(int) ap_find_path_info(const char *uri, const char *path_info);
  64
  65 /**
  66  * Add CGI environment variables required by HTTP/1.1 to the request's
  67  * environment table
  68  * @param r the current request
  69  * @fn void ap_add_cgi_vars(request_rec *r)
  70  */
  71 AP_DECLARE(void) ap_add_cgi_vars(request_rec *r);
  72
  73 /**
  74  * Add common CGI environment variables to the requests environment table
  75  * @param r The current request
  76  * @fn void ap_add_common_vars(request_rec *r)
  77  */
  78 AP_DECLARE(void) ap_add_common_vars(request_rec *r);
  79
  80 /**
  81  * Read headers output from a script, ensuring that the output is valid.  If
  82  * the output is valid, then the headers are added to the headers out of the
  83  * current request
  84  * @param r The current request
  85  * @param f The file to read from
  86  * @param buffer Empty when calling the function.  On output, if there was an
  87  *               error, the string that cause the error is stored here.
  88  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
  89  * @fn int ap_scan_script_header_err(request_rec *r, apr_file_t *f, char *buffer)
  90  */
  91 AP_DECLARE(int) ap_scan_script_header_err(request_rec *r, apr_file_t *f, char *buffer);
  92
  93 /**
  94  * Read headers output from a script, ensuring that the output is valid.  If
  95  * the output is valid, then the headers are added to the headers out of the
  96  * current request
  97  * @param r The current request
  98  * @param f The file to read from
  99  * @param buffer Empty when calling the function.  On output, if there was an
 100  *               error, the string that cause the error is stored here.
 101  * @param module_index The module index to be used for logging
 102  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
 103  */
 104 AP_DECLARE(int) ap_scan_script_header_err_ex(request_rec *r, apr_file_t *f,
 105                                              char *buffer, int module_index);
 106
 107
 108 /**
 109  * Read headers output from a script, ensuring that the output is valid.  If
 110  * the output is valid, then the headers are added to the headers out of the
 111  * current request
 112  * @param r The current request
 113  * @param bb The brigade from which to read
 114  * @param buffer Empty when calling the function.  On output, if there was an
 115  *               error, the string that cause the error is stored here.
 116  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
 117  * @fn int ap_scan_script_header_err_brigade(request_rec *r, apr_bucket_brigade *bb, char *buffer)
 118  */
 119 AP_DECLARE(int) ap_scan_script_header_err_brigade(request_rec *r,
 120                                                   apr_bucket_brigade *bb,
 121                                                   char *buffer);
 122
 123 /**
 124  * Read headers output from a script, ensuring that the output is valid.  If
 125  * the output is valid, then the headers are added to the headers out of the
 126  * current request
 127  * @param r The current request
 128  * @param bb The brigade from which to read
 129  * @param buffer Empty when calling the function.  On output, if there was an
 130  *               error, the string that cause the error is stored here.
 131  * @param module_index The module index to be used for logging
 132  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
 133  */
 134 AP_DECLARE(int) ap_scan_script_header_err_brigade_ex(request_rec *r,
 135                                                      apr_bucket_brigade *bb,
 136                                                      char *buffer,
 137                                                      int module_index);
 138
 139 /**
 140  * Read headers strings from a script, ensuring that the output is valid.  If
 141  * the output is valid, then the headers are added to the headers out of the
 142  * current request
 143  * @param r The current request
 144  * @param buffer Empty when calling the function.  On output, if there was an
 145  *               error, the string that cause the error is stored here.
 146  * @param termch Pointer to the last character parsed.
 147  * @param termarg Pointer to an int to capture the last argument parsed.
 148  *
 149  * The varargs are string arguments to parse consecutively for headers,
 150  * with a NULL argument to terminate the list.
 151  *
 152  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
 153  */
 154 AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs(request_rec *r,
 155                                                       char *buffer,
 156                                                       const char **termch,
 157                                                       int *termarg, ...)
 158                        AP_FN_ATTR_SENTINEL;
 159
 160 /**
 161  * Read headers strings from a script, ensuring that the output is valid.  If
 162  * the output is valid, then the headers are added to the headers out of the
 163  * current request
 164  * @param r The current request
 165  * @param buffer Empty when calling the function.  On output, if there was an
 166  *               error, the string that cause the error is stored here.
 167  * @param module_index The module index to be used for logging
 168  * @param termch Pointer to the last character parsed.
 169  * @param termarg Pointer to an int to capture the last argument parsed.
 170  *
 171  * The varargs are string arguments to parse consecutively for headers,
 172  * with a NULL argument to terminate the list.
 173  *
 174  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
 175  */
 176 AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs_ex(request_rec *r,
 177                                                          char *buffer,
 178                                                          int module_index,
 179                                                          const char **termch,
 180                                                          int *termarg, ...)
 181                        AP_FN_ATTR_SENTINEL;
 182
 183
 184 /**
 185  * Read headers output from a script, ensuring that the output is valid.  If
 186  * the output is valid, then the headers are added to the headers out of the
 187  * current request
 188  * @param r The current request
 189  * @param buffer Empty when calling the function.  On output, if there was an
 190  *               error, the string that cause the error is stored here.
 191  * @param getsfunc Function to read the headers from.  This function should
 192                    act like gets()
 193  * @param getsfunc_data The place to read from
 194  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
 195  */
 196 AP_DECLARE(int) ap_scan_script_header_err_core(request_rec *r, char *buffer,
 197                                                int (*getsfunc) (char *, int, void *),
 198                                                void *getsfunc_data);
 199
 200 /**
 201  * Read headers output from a script, ensuring that the output is valid.  If
 202  * the output is valid, then the headers are added to the headers out of the
 203  * current request
 204  * @param r The current request
 205  * @param buffer Empty when calling the function.  On output, if there was an
 206  *               error, the string that cause the error is stored here.
 207  * @param getsfunc Function to read the headers from.  This function should
 208                    act like gets()
 209  * @param getsfunc_data The place to read from
 210  * @param module_index The module index to be used for logging
 211  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
 212  */
 213 AP_DECLARE(int) ap_scan_script_header_err_core_ex(request_rec *r, char *buffer,
 214                                         int (*getsfunc) (char *, int, void *),
 215                                         void *getsfunc_data, int module_index);
 216
 217
 218 /**
 219  * Parse query args for the request and store in a new table allocated
 220  * from the request pool.
 221  * For args with no value, "1" will be used instead.
 222  * If no query args were specified, the table will be empty.
 223  * @param r The current request
 224  * @param table A new table on output.
 225  */
 226 AP_DECLARE(void) ap_args_to_table(request_rec *r, apr_table_t **table);
 227
 228 #ifdef __cplusplus
 229 }
 230 #endif
 231
 232 #endif  /* !APACHE_UTIL_SCRIPT_H */
 233 /** @} */