getopt.h@ 24061

Last change on this file since 24061 was 23868, checked in by vboxsync, 15 years ago
RTGetOpt: Added RTGetOptFetchValue to fetch an additional value for an argument
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 14.1 KB

Line
1	/** @file
2	* IPRT - Command Line Parsing.
3	*/
4
5	/*
6	* Copyright (C) 2007 Sun Microsystems, Inc.
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	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26	* Clara, CA 95054 USA or visit http://www.sun.com if you need
27	* additional information or have any questions.
28	*/
29
30	#ifndef ___iprt_getopt_h
31	#define ___iprt_getopt_h
32
33
34	#include <iprt/cdefs.h>
35	#include <iprt/types.h>
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 RTGETOPTDEF::fFlags
45	*
46	* @remarks When neither of the RTGETOPT_FLAG_HEX, RTGETOPT_FLAG_OCT and RTGETOPT_FLAG_DEC
47	* flags are specified with a integer value format, RTGetOpt will default to
48	* decimal but recognize the 0x prefix when present. RTGetOpt will not look for
49	* for the octal prefix (0).
50	* @{ */
51	/** Requires no extra argument.
52	* (Can be assumed to be 0 for ever.) */
53	#define RTGETOPT_REQ_NOTHING 0
54	/** A value is required or error will be returned. */
55	#define RTGETOPT_REQ_STRING 1
56	/** The value must be a valid signed 8-bit integer or an error will be returned. */
57	#define RTGETOPT_REQ_INT8 2
58	/** The value must be a valid unsigned 8-bit integer or an error will be returned. */
59	#define RTGETOPT_REQ_UINT8 3
60	/** The value must be a valid signed 16-bit integer or an error will be returned. */
61	#define RTGETOPT_REQ_INT16 4
62	/** The value must be a valid unsigned 16-bit integer or an error will be returned. */
63	#define RTGETOPT_REQ_UINT16 5
64	/** The value must be a valid signed 32-bit integer or an error will be returned. */
65	#define RTGETOPT_REQ_INT32 6
66	/** The value must be a valid unsigned 32-bit integer or an error will be returned. */
67	#define RTGETOPT_REQ_UINT32 7
68	/** The value must be a valid signed 64-bit integer or an error will be returned. */
69	#define RTGETOPT_REQ_INT64 8
70	/** The value must be a valid unsigned 64-bit integer or an error will be returned. */
71	#define RTGETOPT_REQ_UINT64 9
72	/** The value must be a valid IPv4 address.
73	* (Not a name, but 4 values in the 0..255 range with dots separating them). */
74	#define RTGETOPT_REQ_IPV4ADDR 10
75	#if 0
76	/** The value must be a valid IPv4 CIDR.
77	* As with RTGETOPT_REQ_IPV4ADDR, no name.
78	* @todo Mix CIDR with types.h or/and net.h first and find a way to make the
79	* mask optional like with ifconfig. See RTCidrStrToIPv4. */
80	#define RTGETOPT_REQ_IPV4CIDR 11
81	#endif
82	/** The value must be a valid ethernet MAC address. */
83	#define RTGETOPT_REQ_MACADDR 14
84	/** The value must be a valid UUID. */
85	#define RTGETOPT_REQ_UUID 15
86	/** The mask of the valid required types. */
87	#define RTGETOPT_REQ_MASK 15
88	/** Treat the value as hexadecimal - only applicable with the RTGETOPT_REQ_INT. */
89	#define RTGETOPT_FLAG_HEX RT_BIT(16)
90	/** Treat the value as octal - only applicable with the RTGETOPT_REQ_INT. */
91	#define RTGETOPT_FLAG_OCT RT_BIT(17)
92	/** Treat the value as decimal - only applicable with the RTGETOPT_REQ_INT. */
93	#define RTGETOPT_FLAG_DEC RT_BIT(18)
94	/** The index value is attached to the argument - only valid for long arguments. */
95	#define RTGETOPT_FLAG_INDEX RT_BIT(19)
96	/** Mask of valid bits - for validation. */
97	#define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK \
98	\| RTGETOPT_FLAG_HEX \
99	\| RTGETOPT_FLAG_OCT \
100	\| RTGETOPT_FLAG_DEC \
101	\| RTGETOPT_FLAG_INDEX)
102	/** @} */
103
104	/**
105	* An option definition.
106	*/
107	typedef struct RTGETOPTDEF
108	{
109	/** The long option.
110	* This is optional */
111	const char *pszLong;
112	/** The short option character.
113	* This doesn't have to be a character, it may also be a \#define or enum value if
114	* there isn't any short version of this option. Must be greater than 0. */
115	int iShort;
116	/** The flags (RTGETOPT_). /
117	unsigned fFlags;
118	} RTGETOPTDEF;
119	/** Pointer to an option definition. */
120	typedef RTGETOPTDEF *PRTGETOPTDEF;
121	/** Pointer to an const option definition. */
122	typedef const RTGETOPTDEF *PCRTGETOPTDEF;
123
124	/**
125	* Option argument union.
126	*
127	* What ends up here depends on argument format in the option definition.
128	*
129	* @remarks Integers will bet put in the \a i and \a u members and sign/zero extended
130	* according to the signedness indicated by the \a fFlags. So, you can choose
131	* use which ever of the integer members for accessing the value regardless
132	* of restrictions indicated in the \a fFlags.
133	*/
134	typedef union RTGETOPTUNION
135	{
136	/** Pointer to the definition on failure or when the option doesn't take an argument.
137	* This can be NULL for some errors. */
138	PCRTGETOPTDEF pDef;
139	/** A RTGETOPT_REQ_STRING option argument. */
140	const char *psz;
141
142	#if !defined(RT_ARCH_AMD64) && !defined(RT_ARCH_X86)
143	# error "PORTME: big-endian systems will need to fix the layout here to get the next two fields working right"
144	#endif
145
146	/** A RTGETOPT_REQ_INT8 option argument. */
147	int8_t i8;
148	/** A RTGETOPT_REQ_UINT8 option argument . */
149	uint8_t u8;
150	/** A RTGETOPT_REQ_INT16 option argument. */
151	int16_t i16;
152	/** A RTGETOPT_REQ_UINT16 option argument . */
153	uint16_t u16;
154	/** A RTGETOPT_REQ_INT16 option argument. */
155	int32_t i32;
156	/** A RTGETOPT_REQ_UINT32 option argument . */
157	uint32_t u32;
158	/** A RTGETOPT_REQ_INT64 option argument. */
159	int64_t i64;
160	/** A RTGETOPT_REQ_UINT64 option argument. */
161	uint64_t u64;
162	#ifdef ___iprt_net_h
163	/** A RTGETOPT_REQ_IPV4ADDR option argument. */
164	RTNETADDRIPV4 IPv4Addr;
165	#endif
166	/** A RTGETOPT_REQ_MACADDR option argument. */
167	RTMAC MacAddr;
168	/** A RTGETOPT_REQ_UUID option argument. */
169	RTUUID Uuid;
170	/** A signed integer value. */
171	int64_t i;
172	/** An unsigned integer value. */
173	uint64_t u;
174	} RTGETOPTUNION;
175	/** Pointer to an option argument union. */
176	typedef RTGETOPTUNION *PRTGETOPTUNION;
177	/** Pointer to a const option argument union. */
178	typedef RTGETOPTUNION const *PCRTGETOPTUNION;
179
180
181	/**
182	* RTGetOpt state.
183	*/
184	typedef struct RTGETOPTSTATE
185	{
186	/** The next argument. */
187	int iNext;
188	/** Argument array. */
189	char **argv;
190	/** Number of items in argv. */
191	int argc;
192	/** Option definition array. */
193	PCRTGETOPTDEF paOptions;
194	/** Number of items in paOptions. */
195	size_t cOptions;
196	/** The next short option.
197	* (For parsing ls -latrT4 kind of option lists.) */
198	const char *pszNextShort;
199	/** The option definition which matched. NULL otherwise. */
200	PCRTGETOPTDEF pDef;
201	/** The index of an index option, otherwise UINT64_MAX. */
202	uint64_t uIndex;
203	/* More members will be added later for dealing with initial
204	call, optional sorting, '--' and so on. */
205	} RTGETOPTSTATE;
206	/** Pointer to RTGetOpt state. */
207	typedef RTGETOPTSTATE *PRTGETOPTSTATE;
208
209
210	/**
211	* Initialize the RTGetOpt state.
212	*
213	* The passed in argument vector may be sorted if fFlags indicates that this is
214	* desired (to be implemented).
215	*
216	* @returns VINF_SUCCESS, VERR_INVALID_PARAMETER or VERR_INVALID_POINTER.
217	* @param pState The state.
218	*
219	* @param argc Argument count, to be copied from what comes in with
220	* main().
221	* @param argv Argument array, to be copied from what comes in with
222	* main(). This may end up being modified by the
223	* option/argument sorting.
224	* @param paOptions Array of RTGETOPTDEF structures, which must specify what
225	* options are understood by the program.
226	* @param cOptions Number of array items passed in with paOptions.
227	* @param iFirst The argument to start with (in argv).
228	* @param fFlags The flags. MBZ for now.
229	*/
230	RTDECL(int) RTGetOptInit(PRTGETOPTSTATE pState, int argc, char **argv,
231	PCRTGETOPTDEF paOptions, size_t cOptions,
232	int iFirst, uint32_t fFlags);
233
234	/**
235	* Command line argument parser, handling both long and short options and checking
236	* argument formats, if desired.
237	*
238	* This is to be called in a loop until it returns 0 (meaning that all options
239	* were parsed) or a negative value (meaning that an error occured). How non-option
240	* arguments are dealt with depends on the flags passed to RTGetOptInit. The default
241	* (fFlags = 0) is to return VINF_GETOPT_NOT_OPTION with pValueUnion->psz pointing to
242	* the argument string.
243	*
244	* For example, for a program which takes the following options:
245	*
246	* --optwithstring (or -s) and a string argument;
247	* --optwithint (or -i) and a 32-bit signed integer argument;
248	* --verbose (or -v) with no arguments,
249	*
250	* code would look something like this:
251	*
252	* @code
253	int main(int argc, char **argv)
254	{
255	RTR3Init();
256
257	static const RTGETOPTDEF s_aOptions[] =
258	{
259	{ "--optwithstring", 's', RTGETOPT_REQ_STRING },
260	{ "--optwithint", 'i', RTGETOPT_REQ_INT32 },
261	{ "--verbose", 'v', 0 },
262	};
263
264	int ch;
265	RTGETOPTUNION ValueUnion;
266	RTGETOPTSTATE GetState;
267	RTGetOptInit(&GetState, argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), 1, 0);
268	while ((ch = RTGetOpt(&GetState, &ValueUnion)))
269	{
270	// for options that require an argument, ValueUnion has received the value
271	switch (ch)
272	{
273	case 's': // --optwithstring or -s
274	// string argument, copy ValueUnion.psz
275	break;
276
277	case 'i': // --optwithint or -i
278	// integer argument, copy ValueUnion.i32
279	break;
280
281	case 'v': // --verbose or -v
282	g_fOptVerbose = true;
283	break;
284
285	case VINF_GETOPT_NOT_OPTION:
286	// handle non-option argument in ValueUnion.psz.
287	break;
288
289	default:
290	if (ch > 0)
291	{
292	if (RT_C_IS_GRAPH(ch))
293	Error("unhandled option: -%c\n", ch);
294	else
295	Error("unhandled option: %i\n", ch);
296	}
297	else if (ch == VERR_GETOPT_UNKNOWN_OPTION)
298	Error("unknown option: %s\n", ValueUnion.psz);
299	else if (ValueUnion.pDef)
300	Error("%s: %Rrs\n", ValueUnion.pDef->pszLong, ch);
301	else
302	Error("%Rrs\n", ch);
303	return 1;
304	}
305	}
306
307	return 0;
308	}
309	@endcode
310	*
311	* @returns 0 when done parsing.
312	* @returns the iShort value of the option. pState->pDef points to the option
313	* definition which matched.
314	* @returns IPRT error status on parse error.
315	* @returns VINF_GETOPT_NOT_OPTION when encountering a non-option argument and
316	* RTGETOPT_FLAG_SORT was not specified. pValueUnion->psz points to the
317	* argument string.
318	* @returns VERR_GETOPT_UNKNOWN_OPTION when encountering an unknown option.
319	* pValueUnion->psz points to the option string.
320	* @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING and pValueUnion->pDef if
321	* a required argument (aka value) was missing for an option.
322	* @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
323	* argument (aka value) conversion failed.
324	*
325	* @param pState The state previously initialized with RTGetOptInit.
326	* @param pValueUnion Union with value; in the event of an error, psz member
327	* points to erroneous parameter; otherwise, for options
328	* that require an argument, this contains the value of
329	* that argument, depending on the type that is required.
330	*/
331	RTDECL(int) RTGetOpt(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion);
332
333	/**
334	* Fetch an additional value.
335	*
336	* This is used for special cases where an option have more than one value.
337	*
338	*
339	* @returns VINF_SUCCESS on success.
340	* @returns IPRT error status on parse error.
341	* @returns VERR_INVALID_PARAMETER if the flags are wrong.
342	* @returns VERR_GETOPT_UNKNOWN_OPTION when pState->pDef is null.
343	* @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING if there are no more
344	* available arguments. pValueUnion->pDef is NULL.
345	* @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
346	* value conversion failed.
347	*
348	* @param pState The state previously initialized with RTGetOptInit.
349	* @param pValueUnion Union with value; in the event of an error, psz member
350	* points to erroneous parameter; otherwise, for options
351	* that require an argument, this contains the value of
352	* that argument, depending on the type that is required.
353	* @param fFlags The flags.
354	*/
355	RTDECL(int) RTGetOptFetchValue(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion, uint32_t fFlags);
356
357	/** @} */
358
359	RT_C_DECLS_END
360
361	#endif
362

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

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

Download in other formats: