[5767] | 1 | /** @file
|
---|
[8245] | 2 | * IPRT - Command Line Parsing.
|
---|
[5767] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[76553] | 6 | * Copyright (C) 2007-2019 Oracle Corporation
|
---|
[5767] | 7 | *
|
---|
[6000] | 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.
|
---|
[5767] | 24 | */
|
---|
| 25 |
|
---|
[76557] | 26 | #ifndef IPRT_INCLUDED_getopt_h
|
---|
| 27 | #define IPRT_INCLUDED_getopt_h
|
---|
[76507] | 28 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 29 | # pragma once
|
---|
| 30 | #endif
|
---|
[5767] | 31 |
|
---|
| 32 |
|
---|
| 33 | #include <iprt/cdefs.h>
|
---|
| 34 | #include <iprt/types.h>
|
---|
[76431] | 35 | #include <iprt/errcore.h> /* for VINF_GETOPT_NOT_OPTION */
|
---|
[5767] | 36 |
|
---|
[20374] | 37 | RT_C_DECLS_BEGIN
|
---|
[5767] | 38 |
|
---|
| 39 | /** @defgroup grp_rt_getopt RTGetOpt - Command Line Parsing
|
---|
| 40 | * @ingroup grp_rt
|
---|
| 41 | * @{
|
---|
| 42 | */
|
---|
| 43 |
|
---|
[31397] | 44 | /** @name Values for RTGETOPTDEF::fFlags and the fFlags parameter of
|
---|
| 45 | * RTGetOptFetchValue.
|
---|
[8147] | 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).
|
---|
[5843] | 51 | * @{ */
|
---|
[8147] | 52 | /** Requires no extra argument.
|
---|
[5843] | 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
|
---|
[8147] | 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
|
---|
[5843] | 65 | /** The value must be a valid signed 32-bit integer or an error will be returned. */
|
---|
[8147] | 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
|
---|
[17319] | 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
|
---|
[17441] | 76 | /** The value must be a valid IPv4 CIDR.
|
---|
| 77 | * As with RTGETOPT_REQ_IPV4ADDR, no name.
|
---|
[45116] | 78 | */
|
---|
[17441] | 79 | #define RTGETOPT_REQ_IPV4CIDR 11
|
---|
[45116] | 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
|
---|
[17441] | 90 | #endif
|
---|
| 91 | /** The value must be a valid ethernet MAC address. */
|
---|
| 92 | #define RTGETOPT_REQ_MACADDR 14
|
---|
[20809] | 93 | /** The value must be a valid UUID. */
|
---|
| 94 | #define RTGETOPT_REQ_UUID 15
|
---|
[24140] | 95 | /** The value must be a string with value as "on" or "off". */
|
---|
| 96 | #define RTGETOPT_REQ_BOOL_ONOFF 16
|
---|
[40598] | 97 | /** Boolean option accepting a wide range of typical ways of
|
---|
| 98 | * expression true and false. */
|
---|
| 99 | #define RTGETOPT_REQ_BOOL 17
|
---|
[68936] | 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
|
---|
[5843] | 112 | /** The mask of the valid required types. */
|
---|
[24140] | 113 | #define RTGETOPT_REQ_MASK 31
|
---|
[8147] | 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)
|
---|
[23644] | 120 | /** The index value is attached to the argument - only valid for long arguments. */
|
---|
| 121 | #define RTGETOPT_FLAG_INDEX RT_BIT(19)
|
---|
[37665] | 122 | /** Treat the long option as case insensitive. */
|
---|
| 123 | #define RTGETOPT_FLAG_ICASE RT_BIT(20)
|
---|
[8147] | 124 | /** Mask of valid bits - for validation. */
|
---|
[23644] | 125 | #define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK \
|
---|
| 126 | | RTGETOPT_FLAG_HEX \
|
---|
| 127 | | RTGETOPT_FLAG_OCT \
|
---|
| 128 | | RTGETOPT_FLAG_DEC \
|
---|
[37665] | 129 | | RTGETOPT_FLAG_INDEX \
|
---|
| 130 | | RTGETOPT_FLAG_ICASE)
|
---|
[5843] | 131 | /** @} */
|
---|
[5767] | 132 |
|
---|
[5843] | 133 | /**
|
---|
| 134 | * An option definition.
|
---|
[5767] | 135 | */
|
---|
[17091] | 136 | typedef struct RTGETOPTDEF
|
---|
[5767] | 137 | {
|
---|
[5843] | 138 | /** The long option.
|
---|
| 139 | * This is optional */
|
---|
| 140 | const char *pszLong;
|
---|
[8147] | 141 | /** The short option character.
|
---|
| 142 | * This doesn't have to be a character, it may also be a \#define or enum value if
|
---|
[19072] | 143 | * there isn't any short version of this option. Must be greater than 0. */
|
---|
[17088] | 144 | int iShort;
|
---|
[5843] | 145 | /** The flags (RTGETOPT_*). */
|
---|
| 146 | unsigned fFlags;
|
---|
[17091] | 147 | } RTGETOPTDEF;
|
---|
[5843] | 148 | /** Pointer to an option definition. */
|
---|
[17091] | 149 | typedef RTGETOPTDEF *PRTGETOPTDEF;
|
---|
[5843] | 150 | /** Pointer to an const option definition. */
|
---|
[17091] | 151 | typedef const RTGETOPTDEF *PCRTGETOPTDEF;
|
---|
[5767] | 152 |
|
---|
[5843] | 153 | /**
|
---|
| 154 | * Option argument union.
|
---|
[8147] | 155 | *
|
---|
[5843] | 156 | * What ends up here depends on argument format in the option definition.
|
---|
[8147] | 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.
|
---|
[5843] | 162 | */
|
---|
[17091] | 163 | typedef union RTGETOPTUNION
|
---|
[5767] | 164 | {
|
---|
[5843] | 165 | /** Pointer to the definition on failure or when the option doesn't take an argument.
|
---|
| 166 | * This can be NULL for some errors. */
|
---|
[17091] | 167 | PCRTGETOPTDEF pDef;
|
---|
[17319] | 168 | /** A RTGETOPT_REQ_STRING option argument. */
|
---|
[5843] | 169 | const char *psz;
|
---|
[8147] | 170 |
|
---|
[17319] | 171 | /** A RTGETOPT_REQ_INT8 option argument. */
|
---|
[8147] | 172 | int8_t i8;
|
---|
[17319] | 173 | /** A RTGETOPT_REQ_UINT8 option argument . */
|
---|
[8147] | 174 | uint8_t u8;
|
---|
[17319] | 175 | /** A RTGETOPT_REQ_INT16 option argument. */
|
---|
[8147] | 176 | int16_t i16;
|
---|
[17319] | 177 | /** A RTGETOPT_REQ_UINT16 option argument . */
|
---|
[8147] | 178 | uint16_t u16;
|
---|
[17319] | 179 | /** A RTGETOPT_REQ_INT16 option argument. */
|
---|
[5843] | 180 | int32_t i32;
|
---|
[17319] | 181 | /** A RTGETOPT_REQ_UINT32 option argument . */
|
---|
[5843] | 182 | uint32_t u32;
|
---|
[17319] | 183 | /** A RTGETOPT_REQ_INT64 option argument. */
|
---|
[8147] | 184 | int64_t i64;
|
---|
[17319] | 185 | /** A RTGETOPT_REQ_UINT64 option argument. */
|
---|
[8147] | 186 | uint64_t u64;
|
---|
[76557] | 187 | #ifdef IPRT_INCLUDED_net_h
|
---|
[17319] | 188 | /** A RTGETOPT_REQ_IPV4ADDR option argument. */
|
---|
| 189 | RTNETADDRIPV4 IPv4Addr;
|
---|
[45116] | 190 | /** A RTGETOPT_REQ_IPV4CIDR option argument. */
|
---|
[48934] | 191 | struct
|
---|
| 192 | {
|
---|
| 193 | RTNETADDRIPV4 IPv4Network;
|
---|
| 194 | RTNETADDRIPV4 IPv4Netmask;
|
---|
[45116] | 195 | } CidrIPv4;
|
---|
[17319] | 196 | #endif
|
---|
[17441] | 197 | /** A RTGETOPT_REQ_MACADDR option argument. */
|
---|
| 198 | RTMAC MacAddr;
|
---|
[20809] | 199 | /** A RTGETOPT_REQ_UUID option argument. */
|
---|
| 200 | RTUUID Uuid;
|
---|
[24140] | 201 | /** A boolean flag. */
|
---|
| 202 | bool f;
|
---|
[68936] | 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;
|
---|
[17091] | 216 | } RTGETOPTUNION;
|
---|
[5843] | 217 | /** Pointer to an option argument union. */
|
---|
[17091] | 218 | typedef RTGETOPTUNION *PRTGETOPTUNION;
|
---|
[8147] | 219 | /** Pointer to a const option argument union. */
|
---|
[17091] | 220 | typedef RTGETOPTUNION const *PCRTGETOPTUNION;
|
---|
[5767] | 221 |
|
---|
| 222 |
|
---|
| 223 | /**
|
---|
[17091] | 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;
|
---|
[17141] | 238 | /** The next short option.
|
---|
| 239 | * (For parsing ls -latrT4 kind of option lists.) */
|
---|
| 240 | const char *pszNextShort;
|
---|
[18744] | 241 | /** The option definition which matched. NULL otherwise. */
|
---|
| 242 | PCRTGETOPTDEF pDef;
|
---|
[25323] | 243 | /** The index of an index option, otherwise UINT32_MAX. */
|
---|
| 244 | uint32_t uIndex;
|
---|
[26485] | 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. */
|
---|
[17091] | 253 | } RTGETOPTSTATE;
|
---|
| 254 | /** Pointer to RTGetOpt state. */
|
---|
| 255 | typedef RTGETOPTSTATE *PRTGETOPTSTATE;
|
---|
| 256 |
|
---|
| 257 |
|
---|
| 258 | /**
|
---|
| 259 | * Initialize the RTGetOpt state.
|
---|
| 260 | *
|
---|
[17092] | 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.
|
---|
[17091] | 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).
|
---|
[33911] | 276 | * @param fFlags The flags, see RTGETOPTINIT_FLAGS_XXX.
|
---|
[17091] | 277 | */
|
---|
| 278 | RTDECL(int) RTGetOptInit(PRTGETOPTSTATE pState, int argc, char **argv,
|
---|
| 279 | PCRTGETOPTDEF paOptions, size_t cOptions,
|
---|
| 280 | int iFirst, uint32_t fFlags);
|
---|
| 281 |
|
---|
[26485] | 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 |
|
---|
[25351] | 293 | /**
|
---|
[5767] | 294 | * Command line argument parser, handling both long and short options and checking
|
---|
| 295 | * argument formats, if desired.
|
---|
| 296 | *
|
---|
[5843] | 297 | * This is to be called in a loop until it returns 0 (meaning that all options
|
---|
[33540] | 298 | * were parsed) or a negative value (meaning that an error occurred). How non-option
|
---|
[17094] | 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.
|
---|
[5767] | 302 | *
|
---|
| 303 | * For example, for a program which takes the following options:
|
---|
| 304 | *
|
---|
| 305 | * --optwithstring (or -s) and a string argument;
|
---|
[5843] | 306 | * --optwithint (or -i) and a 32-bit signed integer argument;
|
---|
[5767] | 307 | * --verbose (or -v) with no arguments,
|
---|
| 308 | *
|
---|
| 309 | * code would look something like this:
|
---|
| 310 | *
|
---|
| 311 | * @code
|
---|
[18187] | 312 | int main(int argc, char **argv)
|
---|
| 313 | {
|
---|
[31397] | 314 | int rc = RTR3Init();
|
---|
| 315 | if (RT_FAILURE(rc))
|
---|
| 316 | return RTMsgInitFailure(rc);
|
---|
[18187] | 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:
|
---|
[25317] | 351 | return RTGetOptPrintError(ch, &ValueUnion);
|
---|
[18187] | 352 | }
|
---|
| 353 | }
|
---|
| 354 |
|
---|
[31397] | 355 | return RTEXITCODE_SUCCESS;
|
---|
[18187] | 356 | }
|
---|
| 357 | @endcode
|
---|
[5767] | 358 | *
|
---|
[17094] | 359 | * @returns 0 when done parsing.
|
---|
[18744] | 360 | * @returns the iShort value of the option. pState->pDef points to the option
|
---|
| 361 | * definition which matched.
|
---|
[17094] | 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
|
---|
[17096] | 371 | * argument (aka value) conversion failed.
|
---|
[17094] | 372 | *
|
---|
| 373 | * @param pState The state previously initialized with RTGetOptInit.
|
---|
| 374 | * @param pValueUnion Union with value; in the event of an error, psz member
|
---|
[17091] | 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.
|
---|
[5767] | 378 | */
|
---|
[17091] | 379 | RTDECL(int) RTGetOpt(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion);
|
---|
[5767] | 380 |
|
---|
[23868] | 381 | /**
|
---|
[38515] | 382 | * Fetch a value.
|
---|
[23868] | 383 | *
|
---|
[38515] | 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.
|
---|
[23868] | 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.
|
---|
[38515] | 395 | * @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef is
|
---|
| 396 | * unchanged if value conversion failed.
|
---|
[23868] | 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.
|
---|
[31397] | 403 | * @param fFlags What to get, that is RTGETOPT_REQ_XXX.
|
---|
[23868] | 404 | */
|
---|
| 405 | RTDECL(int) RTGetOptFetchValue(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion, uint32_t fFlags);
|
---|
| 406 |
|
---|
[24825] | 407 | /**
|
---|
[64602] | 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 | */
|
---|
[64603] | 418 | RTDECL(char **) RTGetOptNonOptionArrayPtr(PRTGETOPTSTATE pState);
|
---|
[64602] | 419 |
|
---|
| 420 | /**
|
---|
[24825] | 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 | */
|
---|
[26694] | 430 | RTDECL(RTEXITCODE) RTGetOptPrintError(int ch, PCRTGETOPTUNION pValueUnion);
|
---|
[24825] | 431 |
|
---|
[26476] | 432 | /**
|
---|
[69742] | 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 | /**
|
---|
[26476] | 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 | *
|
---|
[45375] | 452 | * This function aims at following the bourne shell string quoting rules.
|
---|
[26476] | 453 | *
|
---|
| 454 | * @returns IPRT status code.
|
---|
| 455 | *
|
---|
| 456 | * @param ppapszArgv Where to return the argument vector. This must be
|
---|
[67598] | 457 | * freed by calling RTGetOptArgvFreeEx or
|
---|
| 458 | * RTGetOptArgvFree.
|
---|
[26476] | 459 | * @param pcArgs Where to return the argument count.
|
---|
| 460 | * @param pszCmdLine The string to parse.
|
---|
[55671] | 461 | * @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags,
|
---|
| 462 | * except RTGETOPTARGV_CNV_UNQUOTED is not supported.
|
---|
[26476] | 463 | * @param pszSeparators String containing the argument separators. If NULL,
|
---|
| 464 | * then space, tab, line feed (\\n) and return (\\r)
|
---|
| 465 | * are used.
|
---|
| 466 | */
|
---|
[55671] | 467 | RTDECL(int) RTGetOptArgvFromString(char ***ppapszArgv, int *pcArgs, const char *pszCmdLine, uint32_t fFlags,
|
---|
| 468 | const char *pszSeparators);
|
---|
[26476] | 469 |
|
---|
| 470 | /**
|
---|
| 471 | * Frees and argument vector returned by RTGetOptStringToArgv.
|
---|
| 472 | *
|
---|
| 473 | * @param papszArgv Argument vector. NULL is fine.
|
---|
| 474 | */
|
---|
[57926] | 475 | RTDECL(void) RTGetOptArgvFree(char **papszArgv);
|
---|
[26476] | 476 |
|
---|
[27347] | 477 | /**
|
---|
[67598] | 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 | /**
|
---|
[27347] | 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.
|
---|
[57926] | 498 | * @param papszArgv The argument vector to convert.
|
---|
[27347] | 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 |
|
---|
[67598] | 503 | /** @name RTGetOptArgvToString, RTGetOptArgvToUtf16String and
|
---|
| 504 | * RTGetOptArgvFromString flags
|
---|
[27347] | 505 | * @{ */
|
---|
| 506 | /** Quote strings according to the Microsoft CRT rules. */
|
---|
[67598] | 507 | #define RTGETOPTARGV_CNV_QUOTE_MS_CRT UINT32_C(0x00000000)
|
---|
[27347] | 508 | /** Quote strings according to the Unix Bourne Shell. */
|
---|
[67598] | 509 | #define RTGETOPTARGV_CNV_QUOTE_BOURNE_SH UINT32_C(0x00000001)
|
---|
[55529] | 510 | /** Don't quote any strings at all. */
|
---|
[67598] | 511 | #define RTGETOPTARGV_CNV_UNQUOTED UINT32_C(0x00000002)
|
---|
[27347] | 512 | /** Mask for the quoting style. */
|
---|
[67598] | 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)
|
---|
[5767] | 519 | /** @} */
|
---|
| 520 |
|
---|
[27347] | 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.
|
---|
[57944] | 528 | * @param papszArgv The argument vector to convert.
|
---|
[27347] | 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 |
|
---|
[20374] | 535 | RT_C_DECLS_END
|
---|
[5767] | 536 |
|
---|
[76585] | 537 | #endif /* !IPRT_INCLUDED_getopt_h */
|
---|
[5767] | 538 |
|
---|