getopt.h@ 95897

Last change on this file since 95897 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
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-2022 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
37	RT_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	*/
136	typedef 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. */
149	typedef RTGETOPTDEF *PRTGETOPTDEF;
150	/** Pointer to an const option definition. */
151	typedef 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	*/
163	typedef 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. */
218	typedef RTGETOPTUNION *PRTGETOPTUNION;
219	/** Pointer to a const option argument union. */
220	typedef RTGETOPTUNION const *PCRTGETOPTUNION;
221
222
223	/**
224	* RTGetOpt state.
225	*/
226	typedef 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. */
255	typedef 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	*/
278	RTDECL(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
312	int 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	* RTGETOPTINIT_FLAGS_OPTS_FIRST was not specified. pValueUnion->psz
365	* points to the 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	*/
379	RTDECL(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	*/
405	RTDECL(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	*/
418	RTDECL(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	*/
430	RTDECL(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	*/
444	RTDECL(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	*/
467	RTDECL(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	*/
475	RTDECL(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	*/
484	RTDECL(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	*/
501	RTDECL(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	*/
531	RTDECL(int) RTGetOptArgvToUtf16String(PRTUTF16 ppwszCmdLine, const char const *papszArgv, uint32_t fFlags);
532
533	/** @} */
534
535	RT_C_DECLS_END
536
537	#endif /* !IPRT_INCLUDED_getopt_h */
538

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: