1
0

options.h 30 KB

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