options.h 37 KB

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