VirtualBox

source: vbox/trunk/include/iprt/getopt.h@ 34575

Last change on this file since 34575 was 33911, checked in by vboxsync, 14 years ago

code -> laptop

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 16.9 KB
Line 
1/** @file
2 * IPRT - Command Line Parsing.
3 */
4
5/*
6 * Copyright (C) 2007 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_getopt_h
27#define ___iprt_getopt_h
28
29
30#include <iprt/cdefs.h>
31#include <iprt/types.h>
32
33RT_C_DECLS_BEGIN
34
35/** @defgroup grp_rt_getopt RTGetOpt - Command Line Parsing
36 * @ingroup grp_rt
37 * @{
38 */
39
40/** @name Values for RTGETOPTDEF::fFlags and the fFlags parameter of
41 * RTGetOptFetchValue.
42 *
43 * @remarks When neither of the RTGETOPT_FLAG_HEX, RTGETOPT_FLAG_OCT and RTGETOPT_FLAG_DEC
44 * flags are specified with a integer value format, RTGetOpt will default to
45 * decimal but recognize the 0x prefix when present. RTGetOpt will not look for
46 * for the octal prefix (0).
47 * @{ */
48/** Requires no extra argument.
49 * (Can be assumed to be 0 for ever.) */
50#define RTGETOPT_REQ_NOTHING 0
51/** A value is required or error will be returned. */
52#define RTGETOPT_REQ_STRING 1
53/** The value must be a valid signed 8-bit integer or an error will be returned. */
54#define RTGETOPT_REQ_INT8 2
55/** The value must be a valid unsigned 8-bit integer or an error will be returned. */
56#define RTGETOPT_REQ_UINT8 3
57/** The value must be a valid signed 16-bit integer or an error will be returned. */
58#define RTGETOPT_REQ_INT16 4
59/** The value must be a valid unsigned 16-bit integer or an error will be returned. */
60#define RTGETOPT_REQ_UINT16 5
61/** The value must be a valid signed 32-bit integer or an error will be returned. */
62#define RTGETOPT_REQ_INT32 6
63/** The value must be a valid unsigned 32-bit integer or an error will be returned. */
64#define RTGETOPT_REQ_UINT32 7
65/** The value must be a valid signed 64-bit integer or an error will be returned. */
66#define RTGETOPT_REQ_INT64 8
67/** The value must be a valid unsigned 64-bit integer or an error will be returned. */
68#define RTGETOPT_REQ_UINT64 9
69/** The value must be a valid IPv4 address.
70 * (Not a name, but 4 values in the 0..255 range with dots separating them). */
71#define RTGETOPT_REQ_IPV4ADDR 10
72#if 0
73/** The value must be a valid IPv4 CIDR.
74 * As with RTGETOPT_REQ_IPV4ADDR, no name.
75 * @todo Mix CIDR with types.h or/and net.h first and find a way to make the
76 * mask optional like with ifconfig. See RTCidrStrToIPv4. */
77#define RTGETOPT_REQ_IPV4CIDR 11
78#endif
79/** The value must be a valid ethernet MAC address. */
80#define RTGETOPT_REQ_MACADDR 14
81/** The value must be a valid UUID. */
82#define RTGETOPT_REQ_UUID 15
83/** The value must be a string with value as "on" or "off". */
84#define RTGETOPT_REQ_BOOL_ONOFF 16
85/** The mask of the valid required types. */
86#define RTGETOPT_REQ_MASK 31
87/** Treat the value as hexadecimal - only applicable with the RTGETOPT_REQ_*INT*. */
88#define RTGETOPT_FLAG_HEX RT_BIT(16)
89/** Treat the value as octal - only applicable with the RTGETOPT_REQ_*INT*. */
90#define RTGETOPT_FLAG_OCT RT_BIT(17)
91/** Treat the value as decimal - only applicable with the RTGETOPT_REQ_*INT*. */
92#define RTGETOPT_FLAG_DEC RT_BIT(18)
93/** The index value is attached to the argument - only valid for long arguments. */
94#define RTGETOPT_FLAG_INDEX RT_BIT(19)
95/** Mask of valid bits - for validation. */
96#define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK \
97 | RTGETOPT_FLAG_HEX \
98 | RTGETOPT_FLAG_OCT \
99 | RTGETOPT_FLAG_DEC \
100 | RTGETOPT_FLAG_INDEX)
101/** @} */
102
103/**
104 * An option definition.
105 */
106typedef struct RTGETOPTDEF
107{
108 /** The long option.
109 * This is optional */
110 const char *pszLong;
111 /** The short option character.
112 * This doesn't have to be a character, it may also be a \#define or enum value if
113 * there isn't any short version of this option. Must be greater than 0. */
114 int iShort;
115 /** The flags (RTGETOPT_*). */
116 unsigned fFlags;
117} RTGETOPTDEF;
118/** Pointer to an option definition. */
119typedef RTGETOPTDEF *PRTGETOPTDEF;
120/** Pointer to an const option definition. */
121typedef const RTGETOPTDEF *PCRTGETOPTDEF;
122
123/**
124 * Option argument union.
125 *
126 * What ends up here depends on argument format in the option definition.
127 *
128 * @remarks Integers will bet put in the \a i and \a u members and sign/zero extended
129 * according to the signedness indicated by the \a fFlags. So, you can choose
130 * use which ever of the integer members for accessing the value regardless
131 * of restrictions indicated in the \a fFlags.
132 */
133typedef union RTGETOPTUNION
134{
135 /** Pointer to the definition on failure or when the option doesn't take an argument.
136 * This can be NULL for some errors. */
137 PCRTGETOPTDEF pDef;
138 /** A RTGETOPT_REQ_STRING option argument. */
139 const char *psz;
140
141 /** A RTGETOPT_REQ_INT8 option argument. */
142 int8_t i8;
143 /** A RTGETOPT_REQ_UINT8 option argument . */
144 uint8_t u8;
145 /** A RTGETOPT_REQ_INT16 option argument. */
146 int16_t i16;
147 /** A RTGETOPT_REQ_UINT16 option argument . */
148 uint16_t u16;
149 /** A RTGETOPT_REQ_INT16 option argument. */
150 int32_t i32;
151 /** A RTGETOPT_REQ_UINT32 option argument . */
152 uint32_t u32;
153 /** A RTGETOPT_REQ_INT64 option argument. */
154 int64_t i64;
155 /** A RTGETOPT_REQ_UINT64 option argument. */
156 uint64_t u64;
157#ifdef ___iprt_net_h
158 /** A RTGETOPT_REQ_IPV4ADDR option argument. */
159 RTNETADDRIPV4 IPv4Addr;
160#endif
161 /** A RTGETOPT_REQ_MACADDR option argument. */
162 RTMAC MacAddr;
163 /** A RTGETOPT_REQ_UUID option argument. */
164 RTUUID Uuid;
165 /** A boolean flag. */
166 bool f;
167} RTGETOPTUNION;
168/** Pointer to an option argument union. */
169typedef RTGETOPTUNION *PRTGETOPTUNION;
170/** Pointer to a const option argument union. */
171typedef RTGETOPTUNION const *PCRTGETOPTUNION;
172
173
174/**
175 * RTGetOpt state.
176 */
177typedef struct RTGETOPTSTATE
178{
179 /** The next argument. */
180 int iNext;
181 /** Argument array. */
182 char **argv;
183 /** Number of items in argv. */
184 int argc;
185 /** Option definition array. */
186 PCRTGETOPTDEF paOptions;
187 /** Number of items in paOptions. */
188 size_t cOptions;
189 /** The next short option.
190 * (For parsing ls -latrT4 kind of option lists.) */
191 const char *pszNextShort;
192 /** The option definition which matched. NULL otherwise. */
193 PCRTGETOPTDEF pDef;
194 /** The index of an index option, otherwise UINT32_MAX. */
195 uint32_t uIndex;
196 /** The flags passed to RTGetOptInit. */
197 uint32_t fFlags;
198 /** Number of non-options that we're skipping during a sorted get. The value
199 * INT32_MAX is used to indicate that there are no more options. This is used
200 * to implement '--'. */
201 int32_t cNonOptions;
202
203 /* More members may be added later for dealing with new features. */
204} RTGETOPTSTATE;
205/** Pointer to RTGetOpt state. */
206typedef RTGETOPTSTATE *PRTGETOPTSTATE;
207
208
209/**
210 * Initialize the RTGetOpt state.
211 *
212 * The passed in argument vector may be sorted if fFlags indicates that this is
213 * desired (to be implemented).
214 *
215 * @returns VINF_SUCCESS, VERR_INVALID_PARAMETER or VERR_INVALID_POINTER.
216 * @param pState The state.
217 *
218 * @param argc Argument count, to be copied from what comes in with
219 * main().
220 * @param argv Argument array, to be copied from what comes in with
221 * main(). This may end up being modified by the
222 * option/argument sorting.
223 * @param paOptions Array of RTGETOPTDEF structures, which must specify what
224 * options are understood by the program.
225 * @param cOptions Number of array items passed in with paOptions.
226 * @param iFirst The argument to start with (in argv).
227 * @param fFlags The flags, see RTGETOPTINIT_FLAGS_XXX.
228 */
229RTDECL(int) RTGetOptInit(PRTGETOPTSTATE pState, int argc, char **argv,
230 PCRTGETOPTDEF paOptions, size_t cOptions,
231 int iFirst, uint32_t fFlags);
232
233/** @name RTGetOptInit flags.
234 * @{ */
235/** Sort the arguments so that options comes first, then non-options. */
236#define RTGETOPTINIT_FLAGS_OPTS_FIRST RT_BIT_32(0)
237/** Prevent add the standard version and help options:
238 * - "--help", "-h" and "-?" returns 'h'.
239 * - "--version" and "-V" return 'V'.
240 */
241#define RTGETOPTINIT_FLAGS_NO_STD_OPTS RT_BIT_32(1)
242/** @} */
243
244/**
245 * Command line argument parser, handling both long and short options and checking
246 * argument formats, if desired.
247 *
248 * This is to be called in a loop until it returns 0 (meaning that all options
249 * were parsed) or a negative value (meaning that an error occurred). How non-option
250 * arguments are dealt with depends on the flags passed to RTGetOptInit. The default
251 * (fFlags = 0) is to return VINF_GETOPT_NOT_OPTION with pValueUnion->psz pointing to
252 * the argument string.
253 *
254 * For example, for a program which takes the following options:
255 *
256 * --optwithstring (or -s) and a string argument;
257 * --optwithint (or -i) and a 32-bit signed integer argument;
258 * --verbose (or -v) with no arguments,
259 *
260 * code would look something like this:
261 *
262 * @code
263int main(int argc, char **argv)
264{
265 int rc = RTR3Init();
266 if (RT_FAILURE(rc))
267 return RTMsgInitFailure(rc);
268
269 static const RTGETOPTDEF s_aOptions[] =
270 {
271 { "--optwithstring", 's', RTGETOPT_REQ_STRING },
272 { "--optwithint", 'i', RTGETOPT_REQ_INT32 },
273 { "--verbose", 'v', 0 },
274 };
275
276 int ch;
277 RTGETOPTUNION ValueUnion;
278 RTGETOPTSTATE GetState;
279 RTGetOptInit(&GetState, argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), 1, 0);
280 while ((ch = RTGetOpt(&GetState, &ValueUnion)))
281 {
282 // for options that require an argument, ValueUnion has received the value
283 switch (ch)
284 {
285 case 's': // --optwithstring or -s
286 // string argument, copy ValueUnion.psz
287 break;
288
289 case 'i': // --optwithint or -i
290 // integer argument, copy ValueUnion.i32
291 break;
292
293 case 'v': // --verbose or -v
294 g_fOptVerbose = true;
295 break;
296
297 case VINF_GETOPT_NOT_OPTION:
298 // handle non-option argument in ValueUnion.psz.
299 break;
300
301 default:
302 return RTGetOptPrintError(ch, &ValueUnion);
303 }
304 }
305
306 return RTEXITCODE_SUCCESS;
307}
308 @endcode
309 *
310 * @returns 0 when done parsing.
311 * @returns the iShort value of the option. pState->pDef points to the option
312 * definition which matched.
313 * @returns IPRT error status on parse error.
314 * @returns VINF_GETOPT_NOT_OPTION when encountering a non-option argument and
315 * RTGETOPT_FLAG_SORT was not specified. pValueUnion->psz points to the
316 * argument string.
317 * @returns VERR_GETOPT_UNKNOWN_OPTION when encountering an unknown option.
318 * pValueUnion->psz points to the option string.
319 * @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING and pValueUnion->pDef if
320 * a required argument (aka value) was missing for an option.
321 * @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
322 * argument (aka value) conversion failed.
323 *
324 * @param pState The state previously initialized with RTGetOptInit.
325 * @param pValueUnion Union with value; in the event of an error, psz member
326 * points to erroneous parameter; otherwise, for options
327 * that require an argument, this contains the value of
328 * that argument, depending on the type that is required.
329 */
330RTDECL(int) RTGetOpt(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion);
331
332/**
333 * Fetch an additional value.
334 *
335 * This is used for special cases where an option have more than one value.
336 *
337 *
338 * @returns VINF_SUCCESS on success.
339 * @returns IPRT error status on parse error.
340 * @returns VERR_INVALID_PARAMETER if the flags are wrong.
341 * @returns VERR_GETOPT_UNKNOWN_OPTION when pState->pDef is null.
342 * @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING if there are no more
343 * available arguments. pValueUnion->pDef is NULL.
344 * @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
345 * value conversion failed.
346 *
347 * @param pState The state previously initialized with RTGetOptInit.
348 * @param pValueUnion Union with value; in the event of an error, psz member
349 * points to erroneous parameter; otherwise, for options
350 * that require an argument, this contains the value of
351 * that argument, depending on the type that is required.
352 * @param fFlags What to get, that is RTGETOPT_REQ_XXX.
353 */
354RTDECL(int) RTGetOptFetchValue(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion, uint32_t fFlags);
355
356/**
357 * Print error messages for a RTGetOpt default case.
358 *
359 * Uses RTMsgError.
360 *
361 * @returns Suitable exit code.
362 *
363 * @param ch The RTGetOpt return value.
364 * @param pValueUnion The value union returned by RTGetOpt.
365 */
366RTDECL(RTEXITCODE) RTGetOptPrintError(int ch, PCRTGETOPTUNION pValueUnion);
367
368/**
369 * Parses the @a pszCmdLine string into an argv array.
370 *
371 * This is useful for converting a response file or similar to an argument
372 * vector that can be used with RTGetOptInit().
373 *
374 * This function aims at following the bourn shell string quoting rules.
375 *
376 * @returns IPRT status code.
377 *
378 * @param ppapszArgv Where to return the argument vector. This must be
379 * freed by calling RTGetOptArgvFree.
380 * @param pcArgs Where to return the argument count.
381 * @param pszCmdLine The string to parse.
382 * @param pszSeparators String containing the argument separators. If NULL,
383 * then space, tab, line feed (\\n) and return (\\r)
384 * are used.
385 */
386RTDECL(int) RTGetOptArgvFromString(char ***ppapszArgv, int *pcArgs, const char *pszCmdLine, const char *pszSeparators);
387
388/**
389 * Frees and argument vector returned by RTGetOptStringToArgv.
390 *
391 * @param papszArgv Argument vector. NULL is fine.
392 */
393RTDECL(void) RTGetOptArgvFree(char **paArgv);
394
395/**
396 * Turns an argv array into a command line string.
397 *
398 * This is useful for calling CreateProcess on Windows, but can also be used for
399 * displaying an argv array.
400 *
401 * This function aims at following the bourn shell string quoting rules.
402 *
403 * @returns IPRT status code.
404 *
405 * @param ppszCmdLine Where to return the command line string. This must
406 * be freed by calling RTStrFree.
407 * @param papszArgs The argument vector to convert.
408 * @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags.
409 */
410RTDECL(int) RTGetOptArgvToString(char **ppszCmdLine, const char * const *papszArgv, uint32_t fFlags);
411
412/** @name RTGetOptArgvToString and RTGetOptArgvToUtf16String flags
413 * @{ */
414/** Quote strings according to the Microsoft CRT rules. */
415#define RTGETOPTARGV_CNV_QUOTE_MS_CRT UINT32_C(0)
416/** Quote strings according to the Unix Bourne Shell. */
417#define RTGETOPTARGV_CNV_QUOTE_BOURNE_SH UINT32_C(1)
418/** Mask for the quoting style. */
419#define RTGETOPTARGV_CNV_QUOTE_MASK UINT32_C(1)
420/** @} */
421
422/**
423 * Convenience wrapper around RTGetOpArgvToString and RTStrToUtf16.
424 *
425 * @returns IPRT status code.
426 *
427 * @param ppwszCmdLine Where to return the command line string. This must
428 * be freed by calling RTUtf16Free.
429 * @param papszArgs The argument vector to convert.
430 * @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags.
431 */
432RTDECL(int) RTGetOptArgvToUtf16String(PRTUTF16 *ppwszCmdLine, const char * const *papszArgv, uint32_t fFlags);
433
434/** @} */
435
436RT_C_DECLS_END
437
438#endif
439
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette