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 #ifndef APR_GETOPT_H 18 #define APR_GETOPT_H 19 20 /** 21 * @file apr_getopt.h 22 * @brief APR Command Arguments (getopt) 23 */ 24 25 #include "apr_pools.h" 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif /* __cplusplus */ 30 31 /** 32 * @defgroup apr_getopt Command Argument Parsing 33 * @ingroup APR 34 * @{ 35 */ 36 37 /** 38 * An @c apr_getopt_t error callback function. 39 * 40 * @a arg is this @c apr_getopt_t's @c errarg member. 41 */ 42 typedef void (apr_getopt_err_fn_t)(void *arg, const char *err, ...); 43 44 /** @see apr_getopt_t */ 45 typedef struct apr_getopt_t apr_getopt_t; 46 47 /** 48 * Structure to store command line argument information. 49 */ 50 struct apr_getopt_t { 51 /** context for processing */ 52 apr_pool_t *cont; 53 /** function to print error message (NULL == no messages) */ 54 apr_getopt_err_fn_t *errfn; 55 /** user defined first arg to pass to error message */ 56 void *errarg; 57 /** index into parent argv vector */ 58 int ind; 59 /** character checked for validity */ 60 int opt; 61 /** reset getopt */ 62 int reset; 63 /** count of arguments */ 64 int argc; 65 /** array of pointers to arguments */ 66 const char **argv; 67 /** argument associated with option */ 68 char const* place; 69 /** set to nonzero to support interleaving options with regular args */ 70 int interleave; 71 /** start of non-option arguments skipped for interleaving */ 72 int skip_start; 73 /** end of non-option arguments skipped for interleaving */ 74 int skip_end; 75 }; 76 77 /** @see apr_getopt_option_t */ 78 typedef struct apr_getopt_option_t apr_getopt_option_t; 79 80 /** 81 * Structure used to describe options that getopt should search for. 82 */ 83 struct apr_getopt_option_t { 84 /** long option name, or NULL if option has no long name */ 85 const char *name; 86 /** option letter, or a value greater than 255 if option has no letter */ 87 int optch; 88 /** nonzero if option takes an argument */ 89 int has_arg; 90 /** a description of the option */ 91 const char *description; 92 }; 93 94 /** 95 * Initialize the arguments for parsing by apr_getopt(). 96 * @param os The options structure created for apr_getopt() 97 * @param cont The pool to operate on 98 * @param argc The number of arguments to parse 99 * @param argv The array of arguments to parse 100 * @remark Arguments 3 and 4 are most commonly argc and argv from main(argc, argv) 101 * The (*os)->errfn is initialized to fprintf(stderr... but may be overridden. 102 */ 103 APR_DECLARE(apr_status_t) apr_getopt_init(apr_getopt_t **os, apr_pool_t *cont, 104 int argc, const char * const *argv); 105 106 /** 107 * Parse the options initialized by apr_getopt_init(). 108 * @param os The apr_opt_t structure returned by apr_getopt_init() 109 * @param opts A string of characters that are acceptable options to the 110 * program. Characters followed by ":" are required to have an 111 * option associated 112 * @param option_ch The next option character parsed 113 * @param option_arg The argument following the option character: 114 * @return There are four potential status values on exit. They are: 115 * <PRE> 116 * APR_EOF -- No more options to parse 117 * APR_BADCH -- Found a bad option character 118 * APR_BADARG -- No argument followed the option flag 119 * APR_SUCCESS -- The next option was found. 120 * </PRE> 121 */ 122 APR_DECLARE(apr_status_t) apr_getopt(apr_getopt_t *os, const char *opts, 123 char *option_ch, const char **option_arg); 124 125 /** 126 * Parse the options initialized by apr_getopt_init(), accepting long 127 * options beginning with "--" in addition to single-character 128 * options beginning with "-". 129 * @param os The apr_getopt_t structure created by apr_getopt_init() 130 * @param opts A pointer to a list of apr_getopt_option_t structures, which 131 * can be initialized with { "name", optch, has_args }. has_args 132 * is nonzero if the option requires an argument. A structure 133 * with an optch value of 0 terminates the list. 134 * @param option_ch Receives the value of "optch" from the apr_getopt_option_t 135 * structure corresponding to the next option matched. 136 * @param option_arg Receives the argument following the option, if any. 137 * @return There are four potential status values on exit. They are: 138 * <PRE> 139 * APR_EOF -- No more options to parse 140 * APR_BADCH -- Found a bad option character 141 * APR_BADARG -- No argument followed the option flag 142 * APR_SUCCESS -- The next option was found. 143 * </PRE> 144 * When APR_SUCCESS is returned, os->ind gives the index of the first 145 * non-option argument. On error, a message will be printed to stdout unless 146 * os->err is set to 0. If os->interleave is set to nonzero, options can come 147 * after arguments, and os->argv will be permuted to leave non-option arguments 148 * at the end (the original argv is unaffected). 149 */ 150 APR_DECLARE(apr_status_t) apr_getopt_long(apr_getopt_t *os, 151 const apr_getopt_option_t *opts, 152 int *option_ch, 153 const char **option_arg); 154 /** @} */ 155 156 #ifdef __cplusplus 157 } 158 #endif 159 160 #endif /* ! APR_GETOPT_H */ 161