getopt.h revision 7e0c3d180b978b8f4b5b33f8e924520248ee3ab3
/** @file
* IPRT - Command Line Parsing.
*/
/*
* Copyright (C) 2007 Sun Microsystems, Inc.
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
#ifndef ___iprt_getopt_h
#define ___iprt_getopt_h
/** @defgroup grp_rt_getopt RTGetOpt - Command Line Parsing
* @ingroup grp_rt
* @{
*/
/** @name RTGETOPTDEF::fFlags
*
* @remarks When neither of the RTGETOPT_FLAG_HEX, RTGETOPT_FLAG_OCT and RTGETOPT_FLAG_DEC
* flags are specified with a integer value format, RTGetOpt will default to
* decimal but recognize the 0x prefix when present. RTGetOpt will not look for
* for the octal prefix (0).
* @{ */
/** Requires no extra argument.
* (Can be assumed to be 0 for ever.) */
#define RTGETOPT_REQ_NOTHING 0
/** A value is required or error will be returned. */
#define RTGETOPT_REQ_STRING 1
/** The value must be a valid signed 8-bit integer or an error will be returned. */
#define RTGETOPT_REQ_INT8 2
/** The value must be a valid unsigned 8-bit integer or an error will be returned. */
#define RTGETOPT_REQ_UINT8 3
/** The value must be a valid signed 16-bit integer or an error will be returned. */
#define RTGETOPT_REQ_INT16 4
/** The value must be a valid unsigned 16-bit integer or an error will be returned. */
#define RTGETOPT_REQ_UINT16 5
/** The value must be a valid signed 32-bit integer or an error will be returned. */
#define RTGETOPT_REQ_INT32 6
/** The value must be a valid unsigned 32-bit integer or an error will be returned. */
#define RTGETOPT_REQ_UINT32 7
/** The value must be a valid signed 64-bit integer or an error will be returned. */
#define RTGETOPT_REQ_INT64 8
/** The value must be a valid unsigned 64-bit integer or an error will be returned. */
#define RTGETOPT_REQ_UINT64 9
/** The value must be a valid IPv4 address.
* (Not a name, but 4 values in the 0..255 range with dots separating them). */
#define RTGETOPT_REQ_IPV4ADDR 10
#if 0
/** The value must be a valid IPv4 CIDR.
* As with RTGETOPT_REQ_IPV4ADDR, no name.
* mask optional like with ifconfig. See RTCidrStrToIPv4. */
#define RTGETOPT_REQ_IPV4CIDR 11
#endif
/** The value must be a valid ethernet MAC address. */
#define RTGETOPT_REQ_MACADDR 14
/** The value must be a valid UUID. */
#define RTGETOPT_REQ_UUID 15
/** The value must be a string with value as "on" or "off". */
#define RTGETOPT_REQ_BOOL_ONOFF 16
/** The mask of the valid required types. */
#define RTGETOPT_REQ_MASK 31
/** Treat the value as hexadecimal - only applicable with the RTGETOPT_REQ_*INT*. */
/** Treat the value as octal - only applicable with the RTGETOPT_REQ_*INT*. */
/** Treat the value as decimal - only applicable with the RTGETOPT_REQ_*INT*. */
/** The index value is attached to the argument - only valid for long arguments. */
/** Mask of valid bits - for validation. */
#define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK \
/** @} */
/**
* An option definition.
*/
typedef struct RTGETOPTDEF
{
/** The long option.
* This is optional */
const char *pszLong;
/** The short option character.
* This doesn't have to be a character, it may also be a \#define or enum value if
* there isn't any short version of this option. Must be greater than 0. */
int iShort;
/** The flags (RTGETOPT_*). */
unsigned fFlags;
} RTGETOPTDEF;
/** Pointer to an option definition. */
typedef RTGETOPTDEF *PRTGETOPTDEF;
/** Pointer to an const option definition. */
typedef const RTGETOPTDEF *PCRTGETOPTDEF;
/**
* Option argument union.
*
* What ends up here depends on argument format in the option definition.
*
* according to the signedness indicated by the \a fFlags. So, you can choose
* use which ever of the integer members for accessing the value regardless
* of restrictions indicated in the \a fFlags.
*/
typedef union RTGETOPTUNION
{
/** Pointer to the definition on failure or when the option doesn't take an argument.
* This can be NULL for some errors. */
/** A RTGETOPT_REQ_STRING option argument. */
const char *psz;
#if !defined(RT_ARCH_AMD64) && !defined(RT_ARCH_X86)
# error "PORTME: big-endian systems will need to fix the layout here to get the next two fields working right"
#endif
/** A RTGETOPT_REQ_INT8 option argument. */
/** A RTGETOPT_REQ_UINT8 option argument . */
/** A RTGETOPT_REQ_INT16 option argument. */
/** A RTGETOPT_REQ_UINT16 option argument . */
/** A RTGETOPT_REQ_INT16 option argument. */
/** A RTGETOPT_REQ_UINT32 option argument . */
/** A RTGETOPT_REQ_INT64 option argument. */
/** A RTGETOPT_REQ_UINT64 option argument. */
#ifdef ___iprt_net_h
/** A RTGETOPT_REQ_IPV4ADDR option argument. */
#endif
/** A RTGETOPT_REQ_MACADDR option argument. */
/** A RTGETOPT_REQ_UUID option argument. */
/** A signed integer value. */
int64_t i;
/** An unsigned integer value. */
uint64_t u;
/** A boolean flag. */
bool f;
/** Pointer to an option argument union. */
typedef RTGETOPTUNION *PRTGETOPTUNION;
/** Pointer to a const option argument union. */
typedef RTGETOPTUNION const *PCRTGETOPTUNION;
/**
* RTGetOpt state.
*/
typedef struct RTGETOPTSTATE
{
/** The next argument. */
int iNext;
/** Argument array. */
char **argv;
/** Number of items in argv. */
int argc;
/** Option definition array. */
/** Number of items in paOptions. */
/** The next short option.
* (For parsing ls -latrT4 kind of option lists.) */
const char *pszNextShort;
/** The option definition which matched. NULL otherwise. */
/** The index of an index option, otherwise UINT32_MAX. */
/* More members will be added later for dealing with initial
call, optional sorting, '--' and so on. */
/** Pointer to RTGetOpt state. */
typedef RTGETOPTSTATE *PRTGETOPTSTATE;
/**
* Initialize the RTGetOpt state.
*
* The passed in argument vector may be sorted if fFlags indicates that this is
* desired (to be implemented).
*
* @returns VINF_SUCCESS, VERR_INVALID_PARAMETER or VERR_INVALID_POINTER.
* @param pState The state.
*
* @param argc Argument count, to be copied from what comes in with
* main().
* @param argv Argument array, to be copied from what comes in with
* main(). This may end up being modified by the
* @param paOptions Array of RTGETOPTDEF structures, which must specify what
* options are understood by the program.
* @param cOptions Number of array items passed in with paOptions.
* @param iFirst The argument to start with (in argv).
* @param fFlags The flags. MBZ for now.
*/
/* *
* Command line argument parser, handling both long and short options and checking
* argument formats, if desired.
*
* This is to be called in a loop until it returns 0 (meaning that all options
* were parsed) or a negative value (meaning that an error occured). How non-option
* arguments are dealt with depends on the flags passed to RTGetOptInit. The default
* (fFlags = 0) is to return VINF_GETOPT_NOT_OPTION with pValueUnion->psz pointing to
* the argument string.
*
* For example, for a program which takes the following options:
*
* --optwithstring (or -s) and a string argument;
* --optwithint (or -i) and a 32-bit signed integer argument;
* --verbose (or -v) with no arguments,
*
* code would look something like this:
*
* @code
int main(int argc, char **argv)
{
RTR3Init();
static const RTGETOPTDEF s_aOptions[] =
{
{ "--optwithstring", 's', RTGETOPT_REQ_STRING },
{ "--optwithint", 'i', RTGETOPT_REQ_INT32 },
{ "--verbose", 'v', 0 },
};
int ch;
RTGETOPTUNION ValueUnion;
RTGETOPTSTATE GetState;
RTGetOptInit(&GetState, argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), 1, 0);
while ((ch = RTGetOpt(&GetState, &ValueUnion)))
{
// for options that require an argument, ValueUnion has received the value
switch (ch)
{
case 's': // --optwithstring or -s
// string argument, copy ValueUnion.psz
break;
case 'i': // --optwithint or -i
// integer argument, copy ValueUnion.i32
break;
case 'v': // --verbose or -v
g_fOptVerbose = true;
break;
case VINF_GETOPT_NOT_OPTION:
// handle non-option argument in ValueUnion.psz.
break;
default:
return RTGetOptPrintError(ch, &ValueUnion);
}
}
return 0;
}
@endcode
*
* @returns 0 when done parsing.
* @returns the iShort value of the option. pState->pDef points to the option
* definition which matched.
* @returns IPRT error status on parse error.
* @returns VINF_GETOPT_NOT_OPTION when encountering a non-option argument and
* RTGETOPT_FLAG_SORT was not specified. pValueUnion->psz points to the
* argument string.
* @returns VERR_GETOPT_UNKNOWN_OPTION when encountering an unknown option.
* pValueUnion->psz points to the option string.
* @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING and pValueUnion->pDef if
* a required argument (aka value) was missing for an option.
* @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
* argument (aka value) conversion failed.
*
* @param pState The state previously initialized with RTGetOptInit.
* @param pValueUnion Union with value; in the event of an error, psz member
* points to erroneous parameter; otherwise, for options
* that require an argument, this contains the value of
* that argument, depending on the type that is required.
*/
/**
* Fetch an additional value.
*
* This is used for special cases where an option have more than one value.
*
*
* @returns VINF_SUCCESS on success.
* @returns IPRT error status on parse error.
* @returns VERR_INVALID_PARAMETER if the flags are wrong.
* @returns VERR_GETOPT_UNKNOWN_OPTION when pState->pDef is null.
* @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING if there are no more
* available arguments. pValueUnion->pDef is NULL.
* @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
* value conversion failed.
*
* @param pState The state previously initialized with RTGetOptInit.
* @param pValueUnion Union with value; in the event of an error, psz member
* points to erroneous parameter; otherwise, for options
* that require an argument, this contains the value of
* that argument, depending on the type that is required.
* @param fFlags The flags.
*/
/**
* Print error messages for a RTGetOpt default case.
*
* Uses RTMsgError.
*
* @returns Suitable exit code.
*
* @param ch The RTGetOpt return value.
* @param pValueUnion The value union returned by RTGetOpt.
*/
/** @} */
#endif