1
0

options.h 34 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976
  1. /* -*- buffer-read-only: t -*- vi: set ro:
  2. *
  3. * DO NOT EDIT THIS FILE (options.h)
  4. *
  5. * It has been AutoGen-ed Saturday July 28, 2007 at 01:01:42 PM PDT
  6. * From the definitions funcs.def
  7. * and the template file options_h
  8. *
  9. * This file defines all the global structures and special values
  10. * used in the automated option processing library.
  11. *
  12. * Automated Options copyright 1992-Y Bruce Korb
  13. *
  14. * AutoOpts is free software: you can redistribute it and/or modify it
  15. * under the terms of the GNU Lesser General Public License as published
  16. * by the Free Software Foundation, either version 3 of the License, or
  17. * (at your option) any later version.
  18. *
  19. * AutoOpts is distributed in the hope that it will be useful, but
  20. * WITHOUT ANY WARRANTY; without even the implied warranty of
  21. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  22. * See the GNU Lesser General Public License for more details.
  23. *
  24. * You should have received a copy of the GNU Lesser General Public License
  25. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  26. */
  27. #ifndef AUTOOPTS_OPTIONS_H_GUARD
  28. #define AUTOOPTS_OPTIONS_H_GUARD 1
  29. #include <sys/types.h>
  30. #if defined(HAVE_STDINT_H)
  31. # include <stdint.h>
  32. #elif defined(HAVE_INTTYPES_H)
  33. # include <inttypes.h>
  34. #endif /* HAVE_STDINT/INTTYPES_H */
  35. #if defined(HAVE_LIMITS_H)
  36. # include <limits.h>
  37. #elif defined(HAVE_SYS_LIMITS_H)
  38. # include <sys/limits.h>
  39. #endif /* HAVE_LIMITS/SYS_LIMITS_H */
  40. #if defined(HAVE_SYSEXITS_H)
  41. # include <sysexits.h>
  42. #endif /* HAVE_SYSEXITS_H */
  43. #ifndef EX_USAGE
  44. # define EX_USAGE 64
  45. #endif
  46. /*
  47. * PUBLIC DEFINES
  48. *
  49. * The following defines may be used in applications that need to test the
  50. * state of an option. To test against these masks and values, a pointer
  51. * to an option descriptor must be obtained. There are two ways:
  52. *
  53. * 1. inside an option processing procedure, it is the second argument,
  54. * conventionally "tOptDesc* pOD".
  55. *
  56. * 2. Outside of an option procedure (or to reference a different option
  57. * descriptor), use either "&DESC( opt_name )" or "&pfx_DESC( opt_name )".
  58. *
  59. * See the relevant generated header file to determine which and what
  60. * values for "opt_name" are available.
  61. */
  62. #define OPTIONS_STRUCT_VERSION 122880
  63. #define OPTIONS_VERSION_STRING "30:0:5"
  64. #define OPTIONS_MINIMUM_VERSION 102400
  65. #define OPTIONS_MIN_VER_STRING "25:0:0"
  66. typedef enum {
  67. OPARG_TYPE_NONE = 0,
  68. OPARG_TYPE_STRING = 1, /* default type/ vanilla string */
  69. OPARG_TYPE_ENUMERATION = 2, /* opt arg is an enum (keyword list) */
  70. OPARG_TYPE_BOOLEAN = 3, /* opt arg is boolean-valued */
  71. OPARG_TYPE_MEMBERSHIP = 4, /* opt arg sets set membership bits */
  72. OPARG_TYPE_NUMERIC = 5, /* opt arg has numeric value */
  73. OPARG_TYPE_HIERARCHY = 6 /* option arg is hierarchical value */
  74. } teOptArgType;
  75. typedef struct optionValue {
  76. teOptArgType valType;
  77. char* pzName;
  78. union {
  79. char strVal[1]; /* OPARG_TYPE_STRING */
  80. unsigned int enumVal; /* OPARG_TYPE_ENUMERATION */
  81. unsigned int boolVal; /* OPARG_TYPE_BOOLEAN */
  82. unsigned long setVal; /* OPARG_TYPE_MEMBERSHIP */
  83. long longVal; /* OPARG_TYPE_NUMERIC */
  84. void* nestVal; /* OPARG_TYPE_HIERARCHY */
  85. } v;
  86. } tOptionValue;
  87. /*
  88. * Bits in the fOptState option descriptor field.
  89. */
  90. typedef enum {
  91. OPTST_SET_ID = 0, /* Set via the "SET_OPT()" macro */
  92. OPTST_PRESET_ID = 1, /* Set via an RC/INI file */
  93. OPTST_DEFINED_ID = 2, /* Set via a command line option */
  94. OPTST_EQUIVALENCE_ID = 4, /* selected by equiv'ed option */
  95. OPTST_DISABLED_ID = 5, /* option is in disabled state */
  96. OPTST_ALLOC_ARG_ID = 6, /* pzOptArg was allocated */
  97. OPTST_NO_INIT_ID = 8, /* option cannot be preset */
  98. OPTST_NUMBER_OPT_ID = 9, /* opt value (flag) is any digit */
  99. OPTST_STACKED_ID = 10, /* opt uses optionStackArg proc */
  100. OPTST_INITENABLED_ID = 11, /* option defaults to enabled */
  101. OPTST_ARG_TYPE_1_ID = 12, /* bit 1 of arg type enum */
  102. OPTST_ARG_TYPE_2_ID = 13, /* bit 2 of arg type enum */
  103. OPTST_ARG_TYPE_3_ID = 14, /* bit 3 of arg type enum */
  104. OPTST_ARG_TYPE_4_ID = 15, /* bit 4 of arg type enum */
  105. OPTST_ARG_OPTIONAL_ID = 16, /* the option arg not required */
  106. OPTST_IMM_ID = 17, /* process opt on first pass */
  107. OPTST_DISABLE_IMM_ID = 18, /* process disablement immed. */
  108. OPTST_OMITTED_ID = 19, /* compiled out of program */
  109. OPTST_MUST_SET_ID = 20, /* must be set or pre-set */
  110. OPTST_DOCUMENT_ID = 21, /* opt is for doc only */
  111. OPTST_TWICE_ID = 22, /* process opt twice - imm + reg */
  112. OPTST_DISABLE_TWICE_ID = 23 /* process disabled option twice */
  113. } opt_state_enum_t;
  114. #define OPTST_INIT 0U
  115. #define OPTST_SET (1U << OPTST_SET_ID)
  116. #define OPTST_PRESET (1U << OPTST_PRESET_ID)
  117. #define OPTST_DEFINED (1U << OPTST_DEFINED_ID)
  118. #define OPTST_EQUIVALENCE (1U << OPTST_EQUIVALENCE_ID)
  119. #define OPTST_DISABLED (1U << OPTST_DISABLED_ID)
  120. #define OPTST_ALLOC_ARG (1U << OPTST_ALLOC_ARG_ID)
  121. #define OPTST_NO_INIT (1U << OPTST_NO_INIT_ID)
  122. #define OPTST_NUMBER_OPT (1U << OPTST_NUMBER_OPT_ID)
  123. #define OPTST_STACKED (1U << OPTST_STACKED_ID)
  124. #define OPTST_INITENABLED (1U << OPTST_INITENABLED_ID)
  125. #define OPTST_ARG_TYPE_1 (1U << OPTST_ARG_TYPE_1_ID)
  126. #define OPTST_ARG_TYPE_2 (1U << OPTST_ARG_TYPE_2_ID)
  127. #define OPTST_ARG_TYPE_3 (1U << OPTST_ARG_TYPE_3_ID)
  128. #define OPTST_ARG_TYPE_4 (1U << OPTST_ARG_TYPE_4_ID)
  129. #define OPTST_ARG_OPTIONAL (1U << OPTST_ARG_OPTIONAL_ID)
  130. #define OPTST_IMM (1U << OPTST_IMM_ID)
  131. #define OPTST_DISABLE_IMM (1U << OPTST_DISABLE_IMM_ID)
  132. #define OPTST_OMITTED (1U << OPTST_OMITTED_ID)
  133. #define OPTST_MUST_SET (1U << OPTST_MUST_SET_ID)
  134. #define OPTST_DOCUMENT (1U << OPTST_DOCUMENT_ID)
  135. #define OPTST_TWICE (1U << OPTST_TWICE_ID)
  136. #define OPTST_DISABLE_TWICE (1U << OPTST_DISABLE_TWICE_ID)
  137. #define OPT_STATE_MASK 0x00FFFF77U
  138. #define OPTST_SET_MASK ( \
  139. OPTST_SET | \
  140. OPTST_PRESET | \
  141. OPTST_DEFINED )
  142. #define OPTST_MUTABLE_MASK ( \
  143. OPTST_SET | \
  144. OPTST_PRESET | \
  145. OPTST_DEFINED | \
  146. OPTST_EQUIVALENCE | \
  147. OPTST_DISABLED | \
  148. OPTST_ALLOC_ARG )
  149. #define OPTST_SELECTED_MASK ( \
  150. OPTST_SET | \
  151. OPTST_DEFINED )
  152. #define OPTST_ARG_TYPE_MASK ( \
  153. OPTST_ARG_TYPE_1 | \
  154. OPTST_ARG_TYPE_2 | \
  155. OPTST_ARG_TYPE_3 | \
  156. OPTST_ARG_TYPE_4 )
  157. #ifdef NO_OPTIONAL_OPT_ARGS
  158. # undef OPTST_ARG_OPTIONAL
  159. # define OPTST_ARG_OPTIONAL 0
  160. #endif
  161. #define OPTST_PERSISTENT_MASK (~OPTST_MUTABLE_MASK)
  162. #define SELECTED_OPT( pod ) ((pod)->fOptState & OPTST_SELECTED_MASK)
  163. #define UNUSED_OPT( pod ) (((pod)->fOptState & OPTST_SET_MASK) == 0)
  164. #define DISABLED_OPT( pod ) ((pod)->fOptState & OPTST_DISABLED)
  165. #define OPTION_STATE( pod ) ((pod)->fOptState)
  166. #define OPTST_SET_ARGTYPE(n) ((n) << OPTST_ARG_TYPE_1_ID)
  167. #define OPTST_GET_ARGTYPE(f) (((f) & OPTST_ARG_TYPE_MASK)>>OPTST_ARG_TYPE_1_ID)
  168. /*
  169. * PRIVATE INTERFACES
  170. *
  171. * The following values are used in the generated code to communicate
  172. * with the option library procedures. They are not for public use
  173. * and may be subject to change.
  174. */
  175. /*
  176. * Define the processing state flags
  177. */
  178. typedef enum {
  179. OPTPROC_LONGOPT_ID = 0, /* Process long style options */
  180. OPTPROC_SHORTOPT_ID = 1, /* Process short style "flags" */
  181. OPTPROC_ERRSTOP_ID = 2, /* Stop on argument errors */
  182. OPTPROC_DISABLEDOPT_ID = 3, /* Current option is disabled */
  183. OPTPROC_NO_REQ_OPT_ID = 4, /* no options are required */
  184. OPTPROC_NUM_OPT_ID = 5, /* there is a number option */
  185. OPTPROC_INITDONE_ID = 6, /* have initializations been done? */
  186. OPTPROC_NEGATIONS_ID = 7, /* any negation options? */
  187. OPTPROC_ENVIRON_ID = 8, /* check environment? */
  188. OPTPROC_NO_ARGS_ID = 9, /* Disallow remaining arguments */
  189. OPTPROC_ARGS_REQ_ID = 10, /* Require arguments after options */
  190. OPTPROC_REORDER_ID = 11, /* reorder operands after options */
  191. OPTPROC_GNUUSAGE_ID = 12, /* emit usage in GNU style */
  192. OPTPROC_TRANSLATE_ID = 13, /* Translate strings in tOptions */
  193. OPTPROC_HAS_IMMED_ID = 14, /* program defines immed options */
  194. OPTPROC_PRESETTING_ID = 19 /* opt processing in preset state */
  195. } optproc_state_enum_t;
  196. #define OPTPROC_NONE 0U
  197. #define OPTPROC_LONGOPT (1U << OPTPROC_LONGOPT_ID)
  198. #define OPTPROC_SHORTOPT (1U << OPTPROC_SHORTOPT_ID)
  199. #define OPTPROC_ERRSTOP (1U << OPTPROC_ERRSTOP_ID)
  200. #define OPTPROC_DISABLEDOPT (1U << OPTPROC_DISABLEDOPT_ID)
  201. #define OPTPROC_NO_REQ_OPT (1U << OPTPROC_NO_REQ_OPT_ID)
  202. #define OPTPROC_NUM_OPT (1U << OPTPROC_NUM_OPT_ID)
  203. #define OPTPROC_INITDONE (1U << OPTPROC_INITDONE_ID)
  204. #define OPTPROC_NEGATIONS (1U << OPTPROC_NEGATIONS_ID)
  205. #define OPTPROC_ENVIRON (1U << OPTPROC_ENVIRON_ID)
  206. #define OPTPROC_NO_ARGS (1U << OPTPROC_NO_ARGS_ID)
  207. #define OPTPROC_ARGS_REQ (1U << OPTPROC_ARGS_REQ_ID)
  208. #define OPTPROC_REORDER (1U << OPTPROC_REORDER_ID)
  209. #define OPTPROC_GNUUSAGE (1U << OPTPROC_GNUUSAGE_ID)
  210. #define OPTPROC_TRANSLATE (1U << OPTPROC_TRANSLATE_ID)
  211. #define OPTPROC_HAS_IMMED (1U << OPTPROC_HAS_IMMED_ID)
  212. #define OPTPROC_PRESETTING (1U << OPTPROC_PRESETTING_ID)
  213. #define OPTPROC_STATE_MASK 0x00087FFFU
  214. #define STMTS(s) do { s; } while (0)
  215. /*
  216. * The following must be #defined instead of typedef-ed
  217. * because "static const" cannot both be applied to a type,
  218. * tho each individually can...so they all are
  219. */
  220. #define tSCC static char const
  221. #define tCC char const
  222. #define tAoSC static char
  223. #define tAoUC unsigned char
  224. #define tAoUI unsigned int
  225. #define tAoUL unsigned long
  226. #define tAoUS unsigned short
  227. /*
  228. * It is so disgusting that there must be so many ways
  229. * of specifying TRUE and FALSE.
  230. */
  231. typedef enum { AG_FALSE = 0, AG_TRUE } ag_bool;
  232. /*
  233. * Define a structure that describes each option and
  234. * a pointer to the procedure that handles it.
  235. * The argument is the count of this flag previously seen.
  236. */
  237. typedef struct options tOptions;
  238. typedef struct optDesc tOptDesc;
  239. typedef struct optNames tOptNames;
  240. /*
  241. * The option procedures do the special processing for each
  242. * option flag that needs it.
  243. */
  244. typedef void (tOptProc)( tOptions* pOpts, tOptDesc* pOptDesc );
  245. typedef tOptProc* tpOptProc;
  246. /*
  247. * The usage procedure will never return. It calls "exit(2)"
  248. * with the "exitCode" argument passed to it.
  249. */
  250. typedef void (tUsageProc)( tOptions* pOpts, int exitCode );
  251. typedef tUsageProc* tpUsageProc;
  252. /*
  253. * Special definitions. "NOLIMIT" is the 'max' value to use when
  254. * a flag may appear multiple times without limit. "NO_EQUIVALENT"
  255. * is an illegal value for 'optIndex' (option description index).
  256. */
  257. #define NOLIMIT USHRT_MAX
  258. #define OPTION_LIMIT SHRT_MAX
  259. #define NO_EQUIVALENT (OPTION_LIMIT+1)
  260. /*
  261. * Special values for optValue. It must not be generatable from the
  262. * computation "optIndex +96". Since "optIndex" is limited to 100, ...
  263. */
  264. #define NUMBER_OPTION '#'
  265. typedef struct argList tArgList;
  266. #define MIN_ARG_ALLOC_CT 6
  267. #define INCR_ARG_ALLOC_CT 8
  268. struct argList {
  269. int useCt;
  270. int allocCt;
  271. tCC* apzArgs[ MIN_ARG_ALLOC_CT ];
  272. };
  273. typedef union {
  274. char const * argString;
  275. uintptr_t argEnum;
  276. uintptr_t argIntptr;
  277. long argInt;
  278. unsigned long argUint;
  279. unsigned int argBool;
  280. } optArgBucket_t;
  281. /*
  282. * Descriptor structure for each option.
  283. * Only the fields marked "PUBLIC" are for public use.
  284. */
  285. struct optDesc {
  286. tAoUS const optIndex; /* PUBLIC */
  287. tAoUS const optValue; /* PUBLIC */
  288. tAoUS optActualIndex; /* PUBLIC */
  289. tAoUS optActualValue; /* PUBLIC */
  290. tAoUS const optEquivIndex; /* PUBLIC */
  291. tAoUS const optMinCt;
  292. tAoUS const optMaxCt;
  293. tAoUS optOccCt; /* PUBLIC */
  294. tAoUI fOptState; /* PUBLIC */
  295. tAoUI reserved;
  296. optArgBucket_t optArg; /* PUBLIC */
  297. # define pzLastArg optArg.argString
  298. void* optCookie; /* PUBLIC */
  299. const int * pOptMust;
  300. const int * pOptCant;
  301. tpOptProc pOptProc;
  302. char const* pzText;
  303. char const* pz_NAME;
  304. char const* pz_Name;
  305. char const* pz_DisableName;
  306. char const* pz_DisablePfx;
  307. };
  308. /*
  309. * Some options need special processing, so we store their
  310. * indexes in a known place:
  311. */
  312. typedef struct optSpecIndex tOptSpecIndex;
  313. struct optSpecIndex {
  314. const tAoUS more_help;
  315. const tAoUS save_opts;
  316. const tAoUS number_option;
  317. const tAoUS default_opt;
  318. };
  319. /*
  320. * The procedure generated for translating option text
  321. */
  322. typedef void (tOptionXlateProc)(void);
  323. struct options {
  324. int const structVersion;
  325. int origArgCt;
  326. char** origArgVect;
  327. unsigned int fOptSet;
  328. unsigned int curOptIdx;
  329. char* pzCurOpt;
  330. char const* pzProgPath;
  331. char const* pzProgName;
  332. char const* const pzPROGNAME;
  333. char const* const pzRcName;
  334. char const* const pzCopyright;
  335. char const* const pzCopyNotice;
  336. char const* const pzFullVersion;
  337. char const* const* const papzHomeList;
  338. char const* const pzUsageTitle;
  339. char const* const pzExplain;
  340. char const* const pzDetail;
  341. tOptDesc* const pOptDesc;
  342. char const* const pzBugAddr;
  343. void* pExtensions;
  344. void* pSavedState;
  345. tpUsageProc pUsageProc;
  346. tOptionXlateProc* pTransProc;
  347. tOptSpecIndex specOptIdx;
  348. int const optCt;
  349. int const presetOptCt;
  350. char const * pzFullUsage;
  351. char const * pzShortUsage;
  352. };
  353. /*
  354. * "token list" structure returned by "string_tokenize()"
  355. */
  356. typedef struct {
  357. unsigned long tkn_ct;
  358. unsigned char* tkn_list[1];
  359. } token_list_t;
  360. /*
  361. * Hide the interface - it pollutes a POSIX claim, but leave it for
  362. * anyone #include-ing this header
  363. */
  364. #define strneqvcmp option_strneqvcmp
  365. #define streqvcmp option_streqvcmp
  366. #define streqvmap option_streqvmap
  367. #define strequate option_strequate
  368. #define strtransform option_strtransform
  369. /*
  370. * This is an output only structure used by text_mmap and text_munmap.
  371. * Clients must not alter the contents and must provide it to both
  372. * the text_mmap and text_munmap procedures. BE ADVISED: if you are
  373. * mapping the file with PROT_WRITE the NUL byte at the end MIGHT NOT
  374. * BE WRITABLE. In any event, that byte is not be written back
  375. * to the source file. ALSO: if "txt_data" is valid and "txt_errno"
  376. * is not zero, then there *may* not be a terminating NUL.
  377. */
  378. typedef struct {
  379. void* txt_data; /* text file data */
  380. size_t txt_size; /* actual file size */
  381. size_t txt_full_size; /* mmaped mem size */
  382. int txt_fd; /* file descriptor */
  383. int txt_zero_fd; /* fd for /dev/zero */
  384. int txt_errno; /* warning code */
  385. int txt_prot; /* "prot" flags */
  386. int txt_flags; /* mapping type */
  387. int txt_alloc; /* if we malloced memory */
  388. } tmap_info_t;
  389. #define TEXT_MMAP_FAILED_ADDR(a) ((void*)(a) == (void*)MAP_FAILED)
  390. #ifdef __cplusplus
  391. extern "C" {
  392. #define CPLUSPLUS_CLOSER }
  393. #else
  394. #define CPLUSPLUS_CLOSER
  395. #endif
  396. /*
  397. * The following routines may be coded into AutoOpts client code:
  398. */
  399. /* From: tokenize.c line 118
  400. *
  401. * ao_string_tokenize - tokenize an input string
  402. *
  403. * Arguments:
  404. * string string to be tokenized
  405. *
  406. * Returns: token_list_t* - pointer to a structure that lists each token
  407. *
  408. * This function will convert one input string into a list of strings.
  409. * The list of strings is derived by separating the input based on
  410. * white space separation. However, if the input contains either single
  411. * or double quote characters, then the text after that character up to
  412. * a matching quote will become the string in the list.
  413. *
  414. * The returned pointer should be deallocated with @code{free(3C)} when
  415. * are done using the data. The data are placed in a single block of
  416. * allocated memory. Do not deallocate individual token/strings.
  417. *
  418. * The structure pointed to will contain at least these two fields:
  419. * @table @samp
  420. * @item tkn_ct
  421. * The number of tokens found in the input string.
  422. * @item tok_list
  423. * An array of @code{tkn_ct + 1} pointers to substring tokens, with
  424. * the last pointer set to NULL.
  425. * @end table
  426. *
  427. * There are two types of quoted strings: single quoted (@code{'}) and
  428. * double quoted (@code{"}). Singly quoted strings are fairly raw in that
  429. * escape characters (@code{\\}) are simply another character, except when
  430. * preceding the following characters:
  431. * @example
  432. * @code{\\} double backslashes reduce to one
  433. * @code{'} incorporates the single quote into the string
  434. * @code{\n} suppresses both the backslash and newline character
  435. * @end example
  436. *
  437. * Double quote strings are formed according to the rules of string
  438. * constants in ANSI-C programs.
  439. */
  440. extern token_list_t* ao_string_tokenize( char const* );
  441. /* From: configfile.c line 90
  442. *
  443. * configFileLoad - parse a configuration file
  444. *
  445. * Arguments:
  446. * pzFile the file to load
  447. *
  448. * Returns: const tOptionValue* - An allocated, compound value structure
  449. *
  450. * This routine will load a named configuration file and parse the
  451. * text as a hierarchically valued option. The option descriptor
  452. * created from an option definition file is not used via this interface.
  453. * The returned value is "named" with the input file name and is of
  454. * type "@code{OPARG_TYPE_HIERARCHY}". It may be used in calls to
  455. * @code{optionGetValue()}, @code{optionNextValue()} and
  456. * @code{optionUnloadNested()}.
  457. */
  458. extern const tOptionValue* configFileLoad( char const* );
  459. /* From: configfile.c line 860
  460. *
  461. * optionFileLoad - Load the locatable config files, in order
  462. *
  463. * Arguments:
  464. * pOpts program options descriptor
  465. * pzProg program name
  466. *
  467. * Returns: int - 0 -> SUCCESS, -1 -> FAILURE
  468. *
  469. * This function looks in all the specified directories for a configuration
  470. * file ("rc" file or "ini" file) and processes any found twice. The first
  471. * time through, they are processed in reverse order (last file first). At
  472. * that time, only "immediate action" configurables are processed. For
  473. * example, if the last named file specifies not processing any more
  474. * configuration files, then no more configuration files will be processed.
  475. * Such an option in the @strong{first} named directory will have no effect.
  476. *
  477. * Once the immediate action configurables have been handled, then the
  478. * directories are handled in normal, forward order. In that way, later
  479. * config files can override the settings of earlier config files.
  480. *
  481. * See the AutoOpts documentation for a thorough discussion of the
  482. * config file format.
  483. *
  484. * Configuration files not found or not decipherable are simply ignored.
  485. */
  486. extern int optionFileLoad( tOptions*, char const* );
  487. /* From: configfile.c line 222
  488. *
  489. * optionFindNextValue - find a hierarcicaly valued option instance
  490. *
  491. * Arguments:
  492. * pOptDesc an option with a nested arg type
  493. * pPrevVal the last entry
  494. * name name of value to find
  495. * value the matching value
  496. *
  497. * Returns: const tOptionValue* - a compound value structure
  498. *
  499. * This routine will find the next entry in a nested value option or
  500. * configurable. It will search through the list and return the next entry
  501. * that matches the criteria.
  502. */
  503. extern const tOptionValue* optionFindNextValue( const tOptDesc*, const tOptionValue*, char const*, char const* );
  504. /* From: configfile.c line 148
  505. *
  506. * optionFindValue - find a hierarcicaly valued option instance
  507. *
  508. * Arguments:
  509. * pOptDesc an option with a nested arg type
  510. * name name of value to find
  511. * value the matching value
  512. *
  513. * Returns: const tOptionValue* - a compound value structure
  514. *
  515. * This routine will find an entry in a nested value option or configurable.
  516. * It will search through the list and return a matching entry.
  517. */
  518. extern const tOptionValue* optionFindValue( const tOptDesc*, char const*, char const* );
  519. /* From: restore.c line 165
  520. *
  521. * optionFree - free allocated option processing memory
  522. *
  523. * Arguments:
  524. * pOpts program options descriptor
  525. *
  526. * AutoOpts sometimes allocates memory and puts pointers to it in the
  527. * option state structures. This routine deallocates all such memory.
  528. */
  529. extern void optionFree( tOptions* );
  530. /* From: configfile.c line 291
  531. *
  532. * optionGetValue - get a specific value from a hierarcical list
  533. *
  534. * Arguments:
  535. * pOptValue a hierarchcal value
  536. * valueName name of value to get
  537. *
  538. * Returns: const tOptionValue* - a compound value structure
  539. *
  540. * This routine will find an entry in a nested value option or configurable.
  541. * If "valueName" is NULL, then the first entry is returned. Otherwise,
  542. * the first entry with a name that exactly matches the argument will be
  543. * returned.
  544. */
  545. extern const tOptionValue* optionGetValue( const tOptionValue*, char const* );
  546. /* From: load.c line 498
  547. *
  548. * optionLoadLine - process a string for an option name and value
  549. *
  550. * Arguments:
  551. * pOpts program options descriptor
  552. * pzLine NUL-terminated text
  553. *
  554. * This is a client program callable routine for setting options from, for
  555. * example, the contents of a file that they read in. Only one option may
  556. * appear in the text. It will be treated as a normal (non-preset) option.
  557. *
  558. * When passed a pointer to the option struct and a string, it will find
  559. * the option named by the first token on the string and set the option
  560. * argument to the remainder of the string. The caller must NUL terminate
  561. * the string. Any embedded new lines will be included in the option
  562. * argument. If the input looks like one or more quoted strings, then the
  563. * input will be "cooked". The "cooking" is identical to the string
  564. * formation used in AutoGen definition files (@pxref{basic expression}),
  565. * except that you may not use backquotes.
  566. */
  567. extern void optionLoadLine( tOptions*, char const* );
  568. /* From: configfile.c line 350
  569. *
  570. * optionNextValue - get the next value from a hierarchical list
  571. *
  572. * Arguments:
  573. * pOptValue a hierarchcal list value
  574. * pOldValue a value from this list
  575. *
  576. * Returns: const tOptionValue* - a compound value structure
  577. *
  578. * This routine will return the next entry after the entry passed in. At the
  579. * end of the list, NULL will be returned. If the entry is not found on the
  580. * list, NULL will be returned and "@var{errno}" will be set to EINVAL.
  581. * The "@var{pOldValue}" must have been gotten from a prior call to this
  582. * routine or to "@code{opitonGetValue()}".
  583. */
  584. extern const tOptionValue* optionNextValue( const tOptionValue*, const tOptionValue* );
  585. /* From: usage.c line 107
  586. *
  587. * optionOnlyUsage - Print usage text for just the options
  588. *
  589. * Arguments:
  590. * pOpts program options descriptor
  591. * ex_code exit code for calling exit(3)
  592. *
  593. * This routine will print only the usage for each option.
  594. * This function may be used when the emitted usage must incorporate
  595. * information not available to AutoOpts.
  596. */
  597. extern void optionOnlyUsage( tOptions*, int );
  598. /* From: autoopts.c line 989
  599. *
  600. * optionProcess - this is the main option processing routine
  601. *
  602. * Arguments:
  603. * pOpts program options descriptor
  604. * argc program arg count
  605. * argv program arg vector
  606. *
  607. * Returns: int - the count of the arguments processed
  608. *
  609. * This is the main entry point for processing options. It is intended
  610. * that this procedure be called once at the beginning of the execution of
  611. * a program. Depending on options selected earlier, it is sometimes
  612. * necessary to stop and restart option processing, or to select completely
  613. * different sets of options. This can be done easily, but you generally
  614. * do not want to do this.
  615. *
  616. * The number of arguments processed always includes the program name.
  617. * If one of the arguments is "--", then it is counted and the processing
  618. * stops. If an error was encountered and errors are to be tolerated, then
  619. * the returned value is the index of the argument causing the error.
  620. * A hyphen by itself ("-") will also cause processing to stop and will
  621. * @emph{not} be counted among the processed arguments. A hyphen by itself
  622. * is treated as an operand. Encountering an operand stops option
  623. * processing.
  624. */
  625. extern int optionProcess( tOptions*, int, char** );
  626. /* From: restore.c line 122
  627. *
  628. * optionRestore - restore option state from memory copy
  629. *
  630. * Arguments:
  631. * pOpts program options descriptor
  632. *
  633. * Copy back the option state from saved memory.
  634. * The allocated memory is left intact, so this routine can be
  635. * called repeatedly without having to call optionSaveState again.
  636. * If you are restoring a state that was saved before the first call
  637. * to optionProcess(3AO), then you may change the contents of the
  638. * argc/argv parameters to optionProcess.
  639. */
  640. extern void optionRestore( tOptions* );
  641. /* From: save.c line 311
  642. *
  643. * optionSaveFile - saves the option state to a file
  644. *
  645. * Arguments:
  646. * pOpts program options descriptor
  647. *
  648. * This routine will save the state of option processing to a file. The name
  649. * of that file can be specified with the argument to the @code{--save-opts}
  650. * option, or by appending the @code{rcfile} attribute to the last
  651. * @code{homerc} attribute. If no @code{rcfile} attribute was specified, it
  652. * will default to @code{.@i{programname}rc}. If you wish to specify another
  653. * file, you should invoke the @code{SET_OPT_SAVE_OPTS( @i{filename} )} macro.
  654. */
  655. extern void optionSaveFile( tOptions* );
  656. /* From: restore.c line 70
  657. *
  658. * optionSaveState - saves the option state to memory
  659. *
  660. * Arguments:
  661. * pOpts program options descriptor
  662. *
  663. * This routine will allocate enough memory to save the current option
  664. * processing state. If this routine has been called before, that memory
  665. * will be reused. You may only save one copy of the option state. This
  666. * routine may be called before optionProcess(3AO). If you do call it
  667. * before the first call to optionProcess, then you may also change the
  668. * contents of argc/argv after you call optionRestore(3AO)
  669. *
  670. * In fact, more strongly put: it is safest to only use this function
  671. * before having processed any options. In particular, the saving and
  672. * restoring of stacked string arguments and hierarchical values is
  673. * disabled. The values are not saved.
  674. */
  675. extern void optionSaveState( tOptions* );
  676. /* From: nested.c line 537
  677. *
  678. * optionUnloadNested - Deallocate the memory for a nested value
  679. *
  680. * Arguments:
  681. * pOptVal the hierarchical value
  682. *
  683. * A nested value needs to be deallocated. The pointer passed in should
  684. * have been gotten from a call to @code{configFileLoad()} (See
  685. * @pxref{libopts-configFileLoad}).
  686. */
  687. extern void optionUnloadNested( tOptionValue const * );
  688. /* From: version.c line 41
  689. *
  690. * optionVersion - return the compiled AutoOpts version number
  691. *
  692. * Returns: char const* - the version string in constant memory
  693. *
  694. * Returns the full version string compiled into the library.
  695. * The returned string cannot be modified.
  696. */
  697. extern char const* optionVersion( void );
  698. /* From: ../compat/pathfind.c line 33
  699. *
  700. * pathfind - fild a file in a list of directories
  701. *
  702. * Arguments:
  703. * path colon separated list of search directories
  704. * file the name of the file to look for
  705. * mode the mode bits that must be set to match
  706. *
  707. * Returns: char* - the path to the located file
  708. *
  709. * the pathfind function is available only if HAVE_PATHFIND is not defined
  710. *
  711. * pathfind looks for a a file with name "FILE" and "MODE" access
  712. * along colon delimited "PATH", and returns the full pathname as a
  713. * string, or NULL if not found. If "FILE" contains a slash, then
  714. * it is treated as a relative or absolute path and "PATH" is ignored.
  715. *
  716. * @strong{NOTE}: this function is compiled into @file{libopts} only if
  717. * it is not natively supplied.
  718. *
  719. * The "MODE" argument is a string of option letters chosen from the
  720. * list below:
  721. * @example
  722. * Letter Meaning
  723. * r readable
  724. * w writable
  725. * x executable
  726. * f normal file (NOT IMPLEMENTED)
  727. * b block special (NOT IMPLEMENTED)
  728. * c character special (NOT IMPLEMENTED)
  729. * d directory (NOT IMPLEMENTED)
  730. * p FIFO (pipe) (NOT IMPLEMENTED)
  731. * u set user ID bit (NOT IMPLEMENTED)
  732. * g set group ID bit (NOT IMPLEMENTED)
  733. * k sticky bit (NOT IMPLEMENTED)
  734. * s size nonzero (NOT IMPLEMENTED)
  735. * @end example
  736. */
  737. #ifndef HAVE_PATHFIND
  738. extern char* pathfind( char const*, char const*, char const* );
  739. #endif /* HAVE_PATHFIND */
  740. /* From: streqvcmp.c line 208
  741. *
  742. * strequate - map a list of characters to the same value
  743. *
  744. * Arguments:
  745. * ch_list characters to equivalence
  746. *
  747. * Each character in the input string get mapped to the first character
  748. * in the string.
  749. * This function name is mapped to option_strequate so as to not conflict
  750. * with the POSIX name space.
  751. */
  752. extern void strequate( char const* );
  753. /* From: streqvcmp.c line 118
  754. *
  755. * streqvcmp - compare two strings with an equivalence mapping
  756. *
  757. * Arguments:
  758. * str1 first string
  759. * str2 second string
  760. *
  761. * Returns: int - the difference between two differing characters
  762. *
  763. * Using a character mapping, two strings are compared for "equivalence".
  764. * Each input character is mapped to a comparison character and the
  765. * mapped-to characters are compared for the two NUL terminated input strings.
  766. * This function name is mapped to option_streqvcmp so as to not conflict
  767. * with the POSIX name space.
  768. */
  769. extern int streqvcmp( char const*, char const* );
  770. /* From: streqvcmp.c line 155
  771. *
  772. * streqvmap - Set the character mappings for the streqv functions
  773. *
  774. * Arguments:
  775. * From Input character
  776. * To Mapped-to character
  777. * ct compare length
  778. *
  779. * Set the character mapping. If the count (@code{ct}) is set to zero, then
  780. * the map is cleared by setting all entries in the map to their index
  781. * value. Otherwise, the "@code{From}" character is mapped to the "@code{To}"
  782. * character. If @code{ct} is greater than 1, then @code{From} and @code{To}
  783. * are incremented and the process repeated until @code{ct} entries have been
  784. * set. For example,
  785. * @example
  786. * streqvmap( 'a', 'A', 26 );
  787. * @end example
  788. * @noindent
  789. * will alter the mapping so that all English lower case letters
  790. * will map to upper case.
  791. *
  792. * This function name is mapped to option_streqvmap so as to not conflict
  793. * with the POSIX name space.
  794. */
  795. extern void streqvmap( char, char, int );
  796. /* From: streqvcmp.c line 77
  797. *
  798. * strneqvcmp - compare two strings with an equivalence mapping
  799. *
  800. * Arguments:
  801. * str1 first string
  802. * str2 second string
  803. * ct compare length
  804. *
  805. * Returns: int - the difference between two differing characters
  806. *
  807. * Using a character mapping, two strings are compared for "equivalence".
  808. * Each input character is mapped to a comparison character and the
  809. * mapped-to characters are compared for the two NUL terminated input strings.
  810. * The comparison is limited to @code{ct} bytes.
  811. * This function name is mapped to option_strneqvcmp so as to not conflict
  812. * with the POSIX name space.
  813. */
  814. extern int strneqvcmp( char const*, char const*, int );
  815. /* From: streqvcmp.c line 234
  816. *
  817. * strtransform - convert a string into its mapped-to value
  818. *
  819. * Arguments:
  820. * dest output string
  821. * src input string
  822. *
  823. * Each character in the input string is mapped and the mapped-to
  824. * character is put into the output.
  825. * This function name is mapped to option_strtransform so as to not conflict
  826. * with the POSIX name space.
  827. */
  828. extern void strtransform( char*, char const* );
  829. /* AutoOpts PRIVATE FUNCTIONS: */
  830. tOptProc optionStackArg, optionUnstackArg, optionBooleanVal, optionNumericVal;
  831. extern char* ao_string_cook( char*, int* );
  832. extern unsigned int ao_string_cook_escape_char( char const*, char*, unsigned int );
  833. extern void export_options_to_guile( tOptions* );
  834. extern void genshelloptUsage( tOptions*, int );
  835. extern void optionBooleanVal( tOptions*, tOptDesc* );
  836. extern uintptr_t optionEnumerationVal( tOptions*, tOptDesc*, char const * const *, unsigned int );
  837. extern char const* optionKeywordName( tOptDesc*, unsigned int );
  838. extern void optionLoadOpt( tOptions*, tOptDesc* );
  839. extern ag_bool optionMakePath( char*, int, char const*, char const* );
  840. extern void optionNestedVal( tOptions*, tOptDesc* );
  841. extern void optionNumericVal( tOptions*, tOptDesc* );
  842. extern void optionPagedUsage( tOptions*, tOptDesc* );
  843. extern void optionParseShell( tOptions* );
  844. extern void optionPrintVersion( tOptions*, tOptDesc* );
  845. extern void optionPutShell( tOptions* );
  846. extern void optionSetMembers( tOptions*, tOptDesc*, char const * const *, unsigned int );
  847. extern void optionStackArg( tOptions*, tOptDesc* );
  848. extern void optionUnstackArg( tOptions*, tOptDesc* );
  849. extern void optionUsage( tOptions*, int );
  850. extern void optionVersionStderr( tOptions*, tOptDesc* );
  851. extern void* text_mmap( char const*, int, int, tmap_info_t* );
  852. extern int text_munmap( tmap_info_t* );
  853. CPLUSPLUS_CLOSER
  854. #endif /* AUTOOPTS_OPTIONS_H_GUARD */
  855. /*
  856. * Local Variables:
  857. * c-file-style: "stroustrup"
  858. * indent-tabs-mode: nil
  859. * End:
  860. * options.h ends here */