getopt.h@ 29273

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

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

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

Download in other formats: