VirtualBox

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

Last change on this file since 19944 was 19072, checked in by vboxsync, 16 years ago

IPRT/getopt.h: iShort must be greater than 0.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.4 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__BEGIN_DECLS
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 mask of the valid required types. */
85#define RTGETOPT_REQ_MASK 15
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/** Mask of valid bits - for validation. */
93#define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK | RTGETOPT_FLAG_HEX | RTGETOPT_FLAG_OCT | RTGETOPT_FLAG_DEC )
94/** @} */
95
96/**
97 * An option definition.
98 */
99typedef struct RTGETOPTDEF
100{
101 /** The long option.
102 * This is optional */
103 const char *pszLong;
104 /** The short option character.
105 * This doesn't have to be a character, it may also be a \#define or enum value if
106 * there isn't any short version of this option. Must be greater than 0. */
107 int iShort;
108 /** The flags (RTGETOPT_*). */
109 unsigned fFlags;
110} RTGETOPTDEF;
111/** Pointer to an option definition. */
112typedef RTGETOPTDEF *PRTGETOPTDEF;
113/** Pointer to an const option definition. */
114typedef const RTGETOPTDEF *PCRTGETOPTDEF;
115
116/**
117 * Option argument union.
118 *
119 * What ends up here depends on argument format in the option definition.
120 *
121 * @remarks Integers will bet put in the \a i and \a u members and sign/zero extended
122 * according to the signedness indicated by the \a fFlags. So, you can choose
123 * use which ever of the integer members for accessing the value regardless
124 * of restrictions indicated in the \a fFlags.
125 */
126typedef union RTGETOPTUNION
127{
128 /** Pointer to the definition on failure or when the option doesn't take an argument.
129 * This can be NULL for some errors. */
130 PCRTGETOPTDEF pDef;
131 /** A RTGETOPT_REQ_STRING option argument. */
132 const char *psz;
133
134#if !defined(RT_ARCH_AMD64) && !defined(RT_ARCH_X86)
135# error "PORTME: big-endian systems will need to fix the layout here to get the next two fields working right"
136#endif
137
138 /** A RTGETOPT_REQ_INT8 option argument. */
139 int8_t i8;
140 /** A RTGETOPT_REQ_UINT8 option argument . */
141 uint8_t u8;
142 /** A RTGETOPT_REQ_INT16 option argument. */
143 int16_t i16;
144 /** A RTGETOPT_REQ_UINT16 option argument . */
145 uint16_t u16;
146 /** A RTGETOPT_REQ_INT16 option argument. */
147 int32_t i32;
148 /** A RTGETOPT_REQ_UINT32 option argument . */
149 uint32_t u32;
150 /** A RTGETOPT_REQ_INT64 option argument. */
151 int64_t i64;
152 /** A RTGETOPT_REQ_UINT64 option argument. */
153 uint64_t u64;
154#ifdef ___iprt_net_h
155 /** A RTGETOPT_REQ_IPV4ADDR option argument. */
156 RTNETADDRIPV4 IPv4Addr;
157#endif
158 /** A RTGETOPT_REQ_MACADDR option argument. */
159 RTMAC MacAddr;
160 /** A signed integer value. */
161 int64_t i;
162 /** An unsigned integer value. */
163 uint64_t u;
164} RTGETOPTUNION;
165/** Pointer to an option argument union. */
166typedef RTGETOPTUNION *PRTGETOPTUNION;
167/** Pointer to a const option argument union. */
168typedef RTGETOPTUNION const *PCRTGETOPTUNION;
169
170
171/**
172 * RTGetOpt state.
173 */
174typedef struct RTGETOPTSTATE
175{
176 /** The next argument. */
177 int iNext;
178 /** Argument array. */
179 char **argv;
180 /** Number of items in argv. */
181 int argc;
182 /** Option definition array. */
183 PCRTGETOPTDEF paOptions;
184 /** Number of items in paOptions. */
185 size_t cOptions;
186 /** The next short option.
187 * (For parsing ls -latrT4 kind of option lists.) */
188 const char *pszNextShort;
189 /** The option definition which matched. NULL otherwise. */
190 PCRTGETOPTDEF pDef;
191 /* More members will be added later for dealing with initial
192 call, optional sorting, '--' and so on. */
193} RTGETOPTSTATE;
194/** Pointer to RTGetOpt state. */
195typedef RTGETOPTSTATE *PRTGETOPTSTATE;
196
197
198/**
199 * Initialize the RTGetOpt state.
200 *
201 * The passed in argument vector may be sorted if fFlags indicates that this is
202 * desired (to be implemented).
203 *
204 * @returns VINF_SUCCESS, VERR_INVALID_PARAMETER or VERR_INVALID_POINTER.
205 * @param pState The state.
206 *
207 * @param argc Argument count, to be copied from what comes in with
208 * main().
209 * @param argv Argument array, to be copied from what comes in with
210 * main(). This may end up being modified by the
211 * option/argument sorting.
212 * @param paOptions Array of RTGETOPTDEF structures, which must specify what
213 * options are understood by the program.
214 * @param cOptions Number of array items passed in with paOptions.
215 * @param iFirst The argument to start with (in argv).
216 * @param fFlags The flags. MBZ for now.
217 */
218RTDECL(int) RTGetOptInit(PRTGETOPTSTATE pState, int argc, char **argv,
219 PCRTGETOPTDEF paOptions, size_t cOptions,
220 int iFirst, uint32_t fFlags);
221
222/**
223 * Command line argument parser, handling both long and short options and checking
224 * argument formats, if desired.
225 *
226 * This is to be called in a loop until it returns 0 (meaning that all options
227 * were parsed) or a negative value (meaning that an error occured). How non-option
228 * arguments are dealt with depends on the flags passed to RTGetOptInit. The default
229 * (fFlags = 0) is to return VINF_GETOPT_NOT_OPTION with pValueUnion->psz pointing to
230 * the argument string.
231 *
232 * For example, for a program which takes the following options:
233 *
234 * --optwithstring (or -s) and a string argument;
235 * --optwithint (or -i) and a 32-bit signed integer argument;
236 * --verbose (or -v) with no arguments,
237 *
238 * code would look something like this:
239 *
240 * @code
241int main(int argc, char **argv)
242{
243 RTR3Init();
244
245 static const RTGETOPTDEF s_aOptions[] =
246 {
247 { "--optwithstring", 's', RTGETOPT_REQ_STRING },
248 { "--optwithint", 'i', RTGETOPT_REQ_INT32 },
249 { "--verbose", 'v', 0 },
250 };
251
252 int ch;
253 int i = 1;
254 RTGETOPTUNION ValueUnion;
255 RTGETOPTSTATE GetState;
256 RTGetOptInit(&GetState, argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), 1, 0);
257 while ((ch = RTGetOpt(&GetState, &ValueUnion)))
258 {
259 // for options that require an argument, ValueUnion has received the value
260 switch (ch)
261 {
262 case 's': // --optwithstring or -s
263 // string argument, copy ValueUnion.psz
264 break;
265
266 case 'i': // --optwithint or -i
267 // integer argument, copy ValueUnion.i32
268 break;
269
270 case 'v': // --verbose or -v
271 g_fOptVerbose = true;
272 break;
273
274 case VINF_GETOPT_NOT_OPTION:
275 // handle non-option argument in ValueUnion.psz.
276 break;
277
278 default:
279 if (ch > 0)
280 {
281 if (RT_C_IS_GRAPH(ch))
282 Error("unhandled option: -%c\n", ch);
283 else
284 Error("unhandled option: %i\n", ch);
285 }
286 else if (ch == VERR_GETOPT_UNKNOWN_OPTION)
287 Error("unknown option: %s\n", ValueUnion.psz);
288 else if (ValueUnion.pDef)
289 Error("%s: %Rrs\n", ValueUnion.pDef->pszLong, ch);
290 else
291 Error("%Rrs\n", ch);
292 return 1;
293 }
294 }
295
296 return 0;
297}
298 @endcode
299 *
300 * @returns 0 when done parsing.
301 * @returns the iShort value of the option. pState->pDef points to the option
302 * definition which matched.
303 * @returns IPRT error status on parse error.
304 * @returns VINF_GETOPT_NOT_OPTION when encountering a non-option argument and
305 * RTGETOPT_FLAG_SORT was not specified. pValueUnion->psz points to the
306 * argument string.
307 * @returns VERR_GETOPT_UNKNOWN_OPTION when encountering an unknown option.
308 * pValueUnion->psz points to the option string.
309 * @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING and pValueUnion->pDef if
310 * a required argument (aka value) was missing for an option.
311 * @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
312 * argument (aka value) conversion failed.
313 *
314 * @param pState The state previously initialized with RTGetOptInit.
315 * @param pValueUnion Union with value; in the event of an error, psz member
316 * points to erroneous parameter; otherwise, for options
317 * that require an argument, this contains the value of
318 * that argument, depending on the type that is required.
319 */
320RTDECL(int) RTGetOpt(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion);
321
322/** @} */
323
324__END_DECLS
325
326#endif
327
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