VirtualBox

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

Last change on this file since 77807 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 21.2 KB
Line 
1/** @file
2 * IPRT - Command Line Parsing.
3 */
4
5/*
6 * Copyright (C) 2007-2019 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_INCLUDED_getopt_h
27#define IPRT_INCLUDED_getopt_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35#include <iprt/errcore.h> /* for VINF_GETOPT_NOT_OPTION */
36
37RT_C_DECLS_BEGIN
38
39/** @defgroup grp_rt_getopt RTGetOpt - Command Line Parsing
40 * @ingroup grp_rt
41 * @{
42 */
43
44/** @name Values for RTGETOPTDEF::fFlags and the fFlags parameter of
45 * RTGetOptFetchValue.
46 *
47 * @remarks When neither of the RTGETOPT_FLAG_HEX, RTGETOPT_FLAG_OCT and RTGETOPT_FLAG_DEC
48 * flags are specified with a integer value format, RTGetOpt will default to
49 * decimal but recognize the 0x prefix when present. RTGetOpt will not look for
50 * for the octal prefix (0).
51 * @{ */
52/** Requires no extra argument.
53 * (Can be assumed to be 0 for ever.) */
54#define RTGETOPT_REQ_NOTHING 0
55/** A value is required or error will be returned. */
56#define RTGETOPT_REQ_STRING 1
57/** The value must be a valid signed 8-bit integer or an error will be returned. */
58#define RTGETOPT_REQ_INT8 2
59/** The value must be a valid unsigned 8-bit integer or an error will be returned. */
60#define RTGETOPT_REQ_UINT8 3
61/** The value must be a valid signed 16-bit integer or an error will be returned. */
62#define RTGETOPT_REQ_INT16 4
63/** The value must be a valid unsigned 16-bit integer or an error will be returned. */
64#define RTGETOPT_REQ_UINT16 5
65/** The value must be a valid signed 32-bit integer or an error will be returned. */
66#define RTGETOPT_REQ_INT32 6
67/** The value must be a valid unsigned 32-bit integer or an error will be returned. */
68#define RTGETOPT_REQ_UINT32 7
69/** The value must be a valid signed 64-bit integer or an error will be returned. */
70#define RTGETOPT_REQ_INT64 8
71/** The value must be a valid unsigned 64-bit integer or an error will be returned. */
72#define RTGETOPT_REQ_UINT64 9
73/** The value must be a valid IPv4 address.
74 * (Not a name, but 4 values in the 0..255 range with dots separating them). */
75#define RTGETOPT_REQ_IPV4ADDR 10
76/** The value must be a valid IPv4 CIDR.
77 * As with RTGETOPT_REQ_IPV4ADDR, no name.
78 */
79#define RTGETOPT_REQ_IPV4CIDR 11
80#if 0
81/* take placers */
82/** The value must be a valid IPv6 addr
83 * @todo: Add types and parsing routines in (iprt/net.h)
84 */
85#define RTGETOPT_REQ_IPV6ADDR 12
86/** The value must be a valid IPv6 CIDR
87 * @todo: Add types and parsing routines in (iprt/net.h)
88 */
89#define RTGETOPT_REQ_IPV6CIDR 13
90#endif
91/** The value must be a valid ethernet MAC address. */
92#define RTGETOPT_REQ_MACADDR 14
93/** The value must be a valid UUID. */
94#define RTGETOPT_REQ_UUID 15
95/** The value must be a string with value as "on" or "off". */
96#define RTGETOPT_REQ_BOOL_ONOFF 16
97/** Boolean option accepting a wide range of typical ways of
98 * expression true and false. */
99#define RTGETOPT_REQ_BOOL 17
100/** The value must two unsigned 32-bit integer values separated by a colon,
101 * slash, pipe or space(s). */
102#define RTGETOPT_REQ_UINT32_PAIR 18
103/** The value must two unsigned 64-bit integer values separated by a colon,
104 * slash, pipe or space(s). */
105#define RTGETOPT_REQ_UINT64_PAIR 19
106/** The value must at least unsigned 32-bit integer value, optionally
107 * followed by a second separated by a colon, slash, pipe or space(s). */
108#define RTGETOPT_REQ_UINT32_OPTIONAL_PAIR 20
109/** The value must at least unsigned 64-bit integer value, optionally
110 * followed by a second separated by a colon, slash, pipe or space(s). */
111#define RTGETOPT_REQ_UINT64_OPTIONAL_PAIR 21
112/** The mask of the valid required types. */
113#define RTGETOPT_REQ_MASK 31
114/** Treat the value as hexadecimal - only applicable with the RTGETOPT_REQ_*INT*. */
115#define RTGETOPT_FLAG_HEX RT_BIT(16)
116/** Treat the value as octal - only applicable with the RTGETOPT_REQ_*INT*. */
117#define RTGETOPT_FLAG_OCT RT_BIT(17)
118/** Treat the value as decimal - only applicable with the RTGETOPT_REQ_*INT*. */
119#define RTGETOPT_FLAG_DEC RT_BIT(18)
120/** The index value is attached to the argument - only valid for long arguments. */
121#define RTGETOPT_FLAG_INDEX RT_BIT(19)
122/** Treat the long option as case insensitive. */
123#define RTGETOPT_FLAG_ICASE RT_BIT(20)
124/** Mask of valid bits - for validation. */
125#define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK \
126 | RTGETOPT_FLAG_HEX \
127 | RTGETOPT_FLAG_OCT \
128 | RTGETOPT_FLAG_DEC \
129 | RTGETOPT_FLAG_INDEX \
130 | RTGETOPT_FLAG_ICASE)
131/** @} */
132
133/**
134 * An option definition.
135 */
136typedef struct RTGETOPTDEF
137{
138 /** The long option.
139 * This is optional */
140 const char *pszLong;
141 /** The short option character.
142 * This doesn't have to be a character, it may also be a \#define or enum value if
143 * there isn't any short version of this option. Must be greater than 0. */
144 int iShort;
145 /** The flags (RTGETOPT_*). */
146 unsigned fFlags;
147} RTGETOPTDEF;
148/** Pointer to an option definition. */
149typedef RTGETOPTDEF *PRTGETOPTDEF;
150/** Pointer to an const option definition. */
151typedef const RTGETOPTDEF *PCRTGETOPTDEF;
152
153/**
154 * Option argument union.
155 *
156 * What ends up here depends on argument format in the option definition.
157 *
158 * @remarks Integers will bet put in the \a i and \a u members and sign/zero extended
159 * according to the signedness indicated by the \a fFlags. So, you can choose
160 * use which ever of the integer members for accessing the value regardless
161 * of restrictions indicated in the \a fFlags.
162 */
163typedef union RTGETOPTUNION
164{
165 /** Pointer to the definition on failure or when the option doesn't take an argument.
166 * This can be NULL for some errors. */
167 PCRTGETOPTDEF pDef;
168 /** A RTGETOPT_REQ_STRING option argument. */
169 const char *psz;
170
171 /** A RTGETOPT_REQ_INT8 option argument. */
172 int8_t i8;
173 /** A RTGETOPT_REQ_UINT8 option argument . */
174 uint8_t u8;
175 /** A RTGETOPT_REQ_INT16 option argument. */
176 int16_t i16;
177 /** A RTGETOPT_REQ_UINT16 option argument . */
178 uint16_t u16;
179 /** A RTGETOPT_REQ_INT16 option argument. */
180 int32_t i32;
181 /** A RTGETOPT_REQ_UINT32 option argument . */
182 uint32_t u32;
183 /** A RTGETOPT_REQ_INT64 option argument. */
184 int64_t i64;
185 /** A RTGETOPT_REQ_UINT64 option argument. */
186 uint64_t u64;
187#ifdef IPRT_INCLUDED_net_h
188 /** A RTGETOPT_REQ_IPV4ADDR option argument. */
189 RTNETADDRIPV4 IPv4Addr;
190 /** A RTGETOPT_REQ_IPV4CIDR option argument. */
191 struct
192 {
193 RTNETADDRIPV4 IPv4Network;
194 RTNETADDRIPV4 IPv4Netmask;
195 } CidrIPv4;
196#endif
197 /** A RTGETOPT_REQ_MACADDR option argument. */
198 RTMAC MacAddr;
199 /** A RTGETOPT_REQ_UUID option argument. */
200 RTUUID Uuid;
201 /** A boolean flag. */
202 bool f;
203 /** A RTGETOPT_REQ_UINT32_PAIR or RTGETOPT_REQ_UINT32_OPTIONAL_PAIR option
204 * argument. */
205 struct
206 {
207 uint32_t uFirst;
208 uint32_t uSecond; /**< Set to UINT32_MAX if optional and not present. */
209 } PairU32;
210 /** A RTGETOPT_REQ_UINT64_COLON_PAIR option argument. */
211 struct
212 {
213 uint64_t uFirst;
214 uint64_t uSecond; /**< Set to UINT64_MAX if optional and not present. */
215 } PairU64;
216} RTGETOPTUNION;
217/** Pointer to an option argument union. */
218typedef RTGETOPTUNION *PRTGETOPTUNION;
219/** Pointer to a const option argument union. */
220typedef RTGETOPTUNION const *PCRTGETOPTUNION;
221
222
223/**
224 * RTGetOpt state.
225 */
226typedef struct RTGETOPTSTATE
227{
228 /** The next argument. */
229 int iNext;
230 /** Argument array. */
231 char **argv;
232 /** Number of items in argv. */
233 int argc;
234 /** Option definition array. */
235 PCRTGETOPTDEF paOptions;
236 /** Number of items in paOptions. */
237 size_t cOptions;
238 /** The next short option.
239 * (For parsing ls -latrT4 kind of option lists.) */
240 const char *pszNextShort;
241 /** The option definition which matched. NULL otherwise. */
242 PCRTGETOPTDEF pDef;
243 /** The index of an index option, otherwise UINT32_MAX. */
244 uint32_t uIndex;
245 /** The flags passed to RTGetOptInit. */
246 uint32_t fFlags;
247 /** Number of non-options that we're skipping during a sorted get. The value
248 * INT32_MAX is used to indicate that there are no more options. This is used
249 * to implement '--'. */
250 int32_t cNonOptions;
251
252 /* More members may be added later for dealing with new features. */
253} RTGETOPTSTATE;
254/** Pointer to RTGetOpt state. */
255typedef RTGETOPTSTATE *PRTGETOPTSTATE;
256
257
258/**
259 * Initialize the RTGetOpt state.
260 *
261 * The passed in argument vector may be sorted if fFlags indicates that this is
262 * desired (to be implemented).
263 *
264 * @returns VINF_SUCCESS, VERR_INVALID_PARAMETER or VERR_INVALID_POINTER.
265 * @param pState The state.
266 *
267 * @param argc Argument count, to be copied from what comes in with
268 * main().
269 * @param argv Argument array, to be copied from what comes in with
270 * main(). This may end up being modified by the
271 * option/argument sorting.
272 * @param paOptions Array of RTGETOPTDEF structures, which must specify what
273 * options are understood by the program.
274 * @param cOptions Number of array items passed in with paOptions.
275 * @param iFirst The argument to start with (in argv).
276 * @param fFlags The flags, see RTGETOPTINIT_FLAGS_XXX.
277 */
278RTDECL(int) RTGetOptInit(PRTGETOPTSTATE pState, int argc, char **argv,
279 PCRTGETOPTDEF paOptions, size_t cOptions,
280 int iFirst, uint32_t fFlags);
281
282/** @name RTGetOptInit flags.
283 * @{ */
284/** Sort the arguments so that options comes first, then non-options. */
285#define RTGETOPTINIT_FLAGS_OPTS_FIRST RT_BIT_32(0)
286/** Prevent add the standard version and help options:
287 * - "--help", "-h" and "-?" returns 'h'.
288 * - "--version" and "-V" return 'V'.
289 */
290#define RTGETOPTINIT_FLAGS_NO_STD_OPTS RT_BIT_32(1)
291/** @} */
292
293/**
294 * Command line argument parser, handling both long and short options and checking
295 * argument formats, if desired.
296 *
297 * This is to be called in a loop until it returns 0 (meaning that all options
298 * were parsed) or a negative value (meaning that an error occurred). How non-option
299 * arguments are dealt with depends on the flags passed to RTGetOptInit. The default
300 * (fFlags = 0) is to return VINF_GETOPT_NOT_OPTION with pValueUnion->psz pointing to
301 * the argument string.
302 *
303 * For example, for a program which takes the following options:
304 *
305 * --optwithstring (or -s) and a string argument;
306 * --optwithint (or -i) and a 32-bit signed integer argument;
307 * --verbose (or -v) with no arguments,
308 *
309 * code would look something like this:
310 *
311 * @code
312int main(int argc, char **argv)
313{
314 int rc = RTR3Init();
315 if (RT_FAILURE(rc))
316 return RTMsgInitFailure(rc);
317
318 static const RTGETOPTDEF s_aOptions[] =
319 {
320 { "--optwithstring", 's', RTGETOPT_REQ_STRING },
321 { "--optwithint", 'i', RTGETOPT_REQ_INT32 },
322 { "--verbose", 'v', 0 },
323 };
324
325 int ch;
326 RTGETOPTUNION ValueUnion;
327 RTGETOPTSTATE GetState;
328 RTGetOptInit(&GetState, argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), 1, 0);
329 while ((ch = RTGetOpt(&GetState, &ValueUnion)))
330 {
331 // for options that require an argument, ValueUnion has received the value
332 switch (ch)
333 {
334 case 's': // --optwithstring or -s
335 // string argument, copy ValueUnion.psz
336 break;
337
338 case 'i': // --optwithint or -i
339 // integer argument, copy ValueUnion.i32
340 break;
341
342 case 'v': // --verbose or -v
343 g_fOptVerbose = true;
344 break;
345
346 case VINF_GETOPT_NOT_OPTION:
347 // handle non-option argument in ValueUnion.psz.
348 break;
349
350 default:
351 return RTGetOptPrintError(ch, &ValueUnion);
352 }
353 }
354
355 return RTEXITCODE_SUCCESS;
356}
357 @endcode
358 *
359 * @returns 0 when done parsing.
360 * @returns the iShort value of the option. pState->pDef points to the option
361 * definition which matched.
362 * @returns IPRT error status on parse error.
363 * @returns VINF_GETOPT_NOT_OPTION when encountering a non-option argument and
364 * RTGETOPT_FLAG_SORT was not specified. pValueUnion->psz points to the
365 * argument string.
366 * @returns VERR_GETOPT_UNKNOWN_OPTION when encountering an unknown option.
367 * pValueUnion->psz points to the option string.
368 * @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING and pValueUnion->pDef if
369 * a required argument (aka value) was missing for an option.
370 * @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
371 * argument (aka value) conversion failed.
372 *
373 * @param pState The state previously initialized with RTGetOptInit.
374 * @param pValueUnion Union with value; in the event of an error, psz member
375 * points to erroneous parameter; otherwise, for options
376 * that require an argument, this contains the value of
377 * that argument, depending on the type that is required.
378 */
379RTDECL(int) RTGetOpt(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion);
380
381/**
382 * Fetch a value.
383 *
384 * Used to retrive a value argument in a manner similar to what RTGetOpt does
385 * (@a fFlags -> @a pValueUnion). This can be used when handling
386 * VINF_GETOPT_NOT_OPTION, but is equally useful for decoding options that
387 * takes more than one value.
388 *
389 * @returns VINF_SUCCESS on success.
390 * @returns IPRT error status on parse error.
391 * @returns VERR_INVALID_PARAMETER if the flags are wrong.
392 * @returns VERR_GETOPT_UNKNOWN_OPTION when pState->pDef is null.
393 * @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING if there are no more
394 * available arguments. pValueUnion->pDef is NULL.
395 * @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef is
396 * unchanged if value conversion failed.
397 *
398 * @param pState The state previously initialized with RTGetOptInit.
399 * @param pValueUnion Union with value; in the event of an error, psz member
400 * points to erroneous parameter; otherwise, for options
401 * that require an argument, this contains the value of
402 * that argument, depending on the type that is required.
403 * @param fFlags What to get, that is RTGETOPT_REQ_XXX.
404 */
405RTDECL(int) RTGetOptFetchValue(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion, uint32_t fFlags);
406
407/**
408 * Gets the pointer to the argv entry of the current non-option argument.
409 *
410 * This function ASSUMES the previous RTGetOpt() call returned
411 * VINF_GETOPT_NOT_OPTION and require RTGETOPTINIT_FLAGS_OPTS_FIRST to be
412 * specified to RTGetOptInit().
413 *
414 * @returns Pointer to the argv entry of the current non-option. NULL if
415 * (detectable) precondition isn't fullfilled (asserted)
416 * @param pState The state previously initialized with RTGetOptInit.
417 */
418RTDECL(char **) RTGetOptNonOptionArrayPtr(PRTGETOPTSTATE pState);
419
420/**
421 * Print error messages for a RTGetOpt default case.
422 *
423 * Uses RTMsgError.
424 *
425 * @returns Suitable exit code.
426 *
427 * @param ch The RTGetOpt return value.
428 * @param pValueUnion The value union returned by RTGetOpt.
429 */
430RTDECL(RTEXITCODE) RTGetOptPrintError(int ch, PCRTGETOPTUNION pValueUnion);
431
432/**
433 * Formats error messages for a RTGetOpt default case.
434 *
435 * @returns On success, positive count of formatted character excluding the
436 * terminator. On buffer overflow, negative number giving the required
437 * buffer size (including terminator char). (RTStrPrintf2 style.)
438 *
439 * @param pszBuf The buffer to format into.
440 * @param cbBuf The size of the buffer @a pszBuf points to.
441 * @param ch The RTGetOpt return value.
442 * @param pValueUnion The value union returned by RTGetOpt.
443 */
444RTDECL(ssize_t) RTGetOptFormatError(char *pszBuf, size_t cbBuf, int ch, PCRTGETOPTUNION pValueUnion);
445
446/**
447 * Parses the @a pszCmdLine string into an argv array.
448 *
449 * This is useful for converting a response file or similar to an argument
450 * vector that can be used with RTGetOptInit().
451 *
452 * This function aims at following the bourne shell string quoting rules.
453 *
454 * @returns IPRT status code.
455 *
456 * @param ppapszArgv Where to return the argument vector. This must be
457 * freed by calling RTGetOptArgvFreeEx or
458 * RTGetOptArgvFree.
459 * @param pcArgs Where to return the argument count.
460 * @param pszCmdLine The string to parse.
461 * @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags,
462 * except RTGETOPTARGV_CNV_UNQUOTED is not supported.
463 * @param pszSeparators String containing the argument separators. If NULL,
464 * then space, tab, line feed (\\n) and return (\\r)
465 * are used.
466 */
467RTDECL(int) RTGetOptArgvFromString(char ***ppapszArgv, int *pcArgs, const char *pszCmdLine, uint32_t fFlags,
468 const char *pszSeparators);
469
470/**
471 * Frees and argument vector returned by RTGetOptStringToArgv.
472 *
473 * @param papszArgv Argument vector. NULL is fine.
474 */
475RTDECL(void) RTGetOptArgvFree(char **papszArgv);
476
477/**
478 * Frees and argument vector returned by RTGetOptStringToArgv, taking
479 * RTGETOPTARGV_CNV_MODIFY_INPUT into account.
480 *
481 * @param papszArgv Argument vector. NULL is fine.
482 * @param fFlags The flags passed to RTGetOptStringToArgv.
483 */
484RTDECL(void) RTGetOptArgvFreeEx(char **papszArgv, uint32_t fFlags);
485
486/**
487 * Turns an argv array into a command line string.
488 *
489 * This is useful for calling CreateProcess on Windows, but can also be used for
490 * displaying an argv array.
491 *
492 * This function aims at following the bourn shell string quoting rules.
493 *
494 * @returns IPRT status code.
495 *
496 * @param ppszCmdLine Where to return the command line string. This must
497 * be freed by calling RTStrFree.
498 * @param papszArgv The argument vector to convert.
499 * @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags.
500 */
501RTDECL(int) RTGetOptArgvToString(char **ppszCmdLine, const char * const *papszArgv, uint32_t fFlags);
502
503/** @name RTGetOptArgvToString, RTGetOptArgvToUtf16String and
504 * RTGetOptArgvFromString flags
505 * @{ */
506/** Quote strings according to the Microsoft CRT rules. */
507#define RTGETOPTARGV_CNV_QUOTE_MS_CRT UINT32_C(0x00000000)
508/** Quote strings according to the Unix Bourne Shell. */
509#define RTGETOPTARGV_CNV_QUOTE_BOURNE_SH UINT32_C(0x00000001)
510/** Don't quote any strings at all. */
511#define RTGETOPTARGV_CNV_UNQUOTED UINT32_C(0x00000002)
512/** Mask for the quoting style. */
513#define RTGETOPTARGV_CNV_QUOTE_MASK UINT32_C(0x00000003)
514/** Allow RTGetOptArgvFromString to modifying the command line input string.
515 * @note Must use RTGetOptArgvFreeEx to free. */
516#define RTGETOPTARGV_CNV_MODIFY_INPUT UINT32_C(0x00000004)
517/** Valid bits. */
518#define RTGETOPTARGV_CNV_VALID_MASK UINT32_C(0x00000007)
519/** @} */
520
521/**
522 * Convenience wrapper around RTGetOpArgvToString and RTStrToUtf16.
523 *
524 * @returns IPRT status code.
525 *
526 * @param ppwszCmdLine Where to return the command line string. This must
527 * be freed by calling RTUtf16Free.
528 * @param papszArgv The argument vector to convert.
529 * @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags.
530 */
531RTDECL(int) RTGetOptArgvToUtf16String(PRTUTF16 *ppwszCmdLine, const char * const *papszArgv, uint32_t fFlags);
532
533/** @} */
534
535RT_C_DECLS_END
536
537#endif /* !IPRT_INCLUDED_getopt_h */
538
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle
Contact – Privacy/Do Not Sell My Info – Terms of Use