00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as 00002 * applicable. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_GETOPT_H 00018 #define APR_GETOPT_H 00019 00020 /** 00021 * @file apr_getopt.h 00022 * @brief APR Command Arguments (getopt) 00023 */ 00024 00025 #include "apr_pools.h" 00026 00027 #ifdef __cplusplus 00028 extern "C" { 00029 #endif /* __cplusplus */ 00030 00031 /** 00032 * @defgroup apr_getopt Command Argument Parsing 00033 * @ingroup APR 00034 * @{ 00035 */ 00036 00037 /** 00038 * defintion of a error function 00039 */ 00040 typedef void (apr_getopt_err_fn_t)(void *arg, const char *err, ...); 00041 00042 /** @see apr_getopt_t */ 00043 typedef struct apr_getopt_t apr_getopt_t; 00044 00045 /** 00046 * Structure to store command line argument information. 00047 */ 00048 struct apr_getopt_t { 00049 /** context for processing */ 00050 apr_pool_t *cont; 00051 /** function to print error message (NULL == no messages) */ 00052 apr_getopt_err_fn_t *errfn; 00053 /** user defined first arg to pass to error message */ 00054 void *errarg; 00055 /** index into parent argv vector */ 00056 int ind; 00057 /** character checked for validity */ 00058 int opt; 00059 /** reset getopt */ 00060 int reset; 00061 /** count of arguments */ 00062 int argc; 00063 /** array of pointers to arguments */ 00064 const char **argv; 00065 /** argument associated with option */ 00066 char const* place; 00067 /** set to nonzero to support interleaving options with regular args */ 00068 int interleave; 00069 /** start of non-option arguments skipped for interleaving */ 00070 int skip_start; 00071 /** end of non-option arguments skipped for interleaving */ 00072 int skip_end; 00073 }; 00074 00075 /** @see apr_getopt_option_t */ 00076 typedef struct apr_getopt_option_t apr_getopt_option_t; 00077 00078 /** 00079 * Structure used to describe options that getopt should search for. 00080 */ 00081 struct apr_getopt_option_t { 00082 /** long option name, or NULL if option has no long name */ 00083 const char *name; 00084 /** option letter, or a value greater than 255 if option has no letter */ 00085 int optch; 00086 /** nonzero if option takes an argument */ 00087 int has_arg; 00088 /** a description of the option */ 00089 const char *description; 00090 }; 00091 00092 /** 00093 * Initialize the arguments for parsing by apr_getopt(). 00094 * @param os The options structure created for apr_getopt() 00095 * @param cont The pool to operate on 00096 * @param argc The number of arguments to parse 00097 * @param argv The array of arguments to parse 00098 * @remark Arguments 2 and 3 are most commonly argc and argv from main(argc, argv) 00099 * The errfn is initialized to fprintf(stderr... but may be overridden. 00100 */ 00101 APR_DECLARE(apr_status_t) apr_getopt_init(apr_getopt_t **os, apr_pool_t *cont, 00102 int argc, const char * const *argv); 00103 00104 /** 00105 * Parse the options initialized by apr_getopt_init(). 00106 * @param os The apr_opt_t structure returned by apr_getopt_init() 00107 * @param opts A string of characters that are acceptable options to the 00108 * program. Characters followed by ":" are required to have an 00109 * option associated 00110 * @param option_ch The next option character parsed 00111 * @param option_arg The argument following the option character: 00112 * @return There are four potential status values on exit. They are: 00113 * <PRE> 00114 * APR_EOF -- No more options to parse 00115 * APR_BADCH -- Found a bad option character 00116 * APR_BADARG -- No argument followed the option flag 00117 * APR_SUCCESS -- The next option was found. 00118 * </PRE> 00119 */ 00120 APR_DECLARE(apr_status_t) apr_getopt(apr_getopt_t *os, const char *opts, 00121 char *option_ch, const char **option_arg); 00122 00123 /** 00124 * Parse the options initialized by apr_getopt_init(), accepting long 00125 * options beginning with "--" in addition to single-character 00126 * options beginning with "-". 00127 * @param os The apr_getopt_t structure created by apr_getopt_init() 00128 * @param opts A pointer to a list of apr_getopt_option_t structures, which 00129 * can be initialized with { "name", optch, has_args }. has_args 00130 * is nonzero if the option requires an argument. A structure 00131 * with an optch value of 0 terminates the list. 00132 * @param option_ch Receives the value of "optch" from the apr_getopt_option_t 00133 * structure corresponding to the next option matched. 00134 * @param option_arg Receives the argument following the option, if any. 00135 * @return There are four potential status values on exit. They are: 00136 * <PRE> 00137 * APR_EOF -- No more options to parse 00138 * APR_BADCH -- Found a bad option character 00139 * APR_BADARG -- No argument followed the option flag 00140 * APR_SUCCESS -- The next option was found. 00141 * </PRE> 00142 * When APR_SUCCESS is returned, os->ind gives the index of the first 00143 * non-option argument. On error, a message will be printed to stdout unless 00144 * os->err is set to 0. If os->interleave is set to nonzero, options can come 00145 * after arguments, and os->argv will be permuted to leave non-option arguments 00146 * at the end (the original argv is unaffected). 00147 */ 00148 APR_DECLARE(apr_status_t) apr_getopt_long(apr_getopt_t *os, 00149 const apr_getopt_option_t *opts, 00150 int *option_ch, 00151 const char **option_arg); 00152 /** @} */ 00153 00154 #ifdef __cplusplus 00155 } 00156 #endif 00157 00158 #endif /* ! APR_GETOPT_H */