getopt.h revision da97b7ac000d0f02e86c31a4f2767a00d83c6167
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * IPRT - Command Line Parsing.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Copyright (C) 2007 Sun Microsystems, Inc.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * available from http://www.virtualbox.org. This file is free software;
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * you can redistribute it and/or modify it under the terms of the GNU
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * General Public License (GPL) as published by the Free Software
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * The contents of this file may alternatively be used under the terms
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * of the Common Development and Distribution License Version 1.0
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * VirtualBox OSE distribution, in which case the provisions of the
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * CDDL are applicable instead of those of the GPL.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * You may elect to license modified versions of this file under the
70bb61ea2f96e80150e807529ce5df435607706bvboxsync * terms and conditions of either the GPL or the CDDL or both.
23179f1443b03947d85eccc81cbc6b5153a4abf3vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * additional information or have any questions.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** @defgroup grp_rt_getopt RTGetOpt - Command Line Parsing
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @ingroup grp_rt
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** @name RTOPTIONDEF::fFlags
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @remarks When neither of the RTGETOPT_FLAG_HEX, RTGETOPT_FLAG_OCT and RTGETOPT_FLAG_DEC
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * flags are specified with a integer value format, RTGetOpt will default to
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * decimal but recognize the 0x prefix when present. RTGetOpt will not look for
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * for the octal prefix (0).
147e101bcd061b5e085e4a2c0cc9fc35546ff1aavboxsync/** Requires no extra argument.
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * (Can be assumed to be 0 for ever.) */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** A value is required or error will be returned. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** The value must be a valid signed 8-bit integer or an error will be returned. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** The value must be a valid unsigned 8-bit integer or an error will be returned. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** The value must be a valid signed 16-bit integer or an error will be returned. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** The value must be a valid unsigned 16-bit integer or an error will be returned. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** The value must be a valid signed 32-bit integer or an error will be returned. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** The value must be a valid unsigned 32-bit integer or an error will be returned. */
6e12ccc60ac657fb87e27b7a2b26e0a63bebe024vboxsync/** The value must be a valid signed 64-bit integer or an error will be returned. */
6e12ccc60ac657fb87e27b7a2b26e0a63bebe024vboxsync/** The value must be a valid unsigned 64-bit integer or an error will be returned. */
db0ecde8f28fdb4525bc6d94056166c70b02ebb8vboxsync/** The mask of the valid required types. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** Treat the value as hexadecimal - only applicable with the RTGETOPT_REQ_*INT*. */
9353e321b583ed6f2b42414257a5212885575b5cvboxsync/** Treat the value as octal - only applicable with the RTGETOPT_REQ_*INT*. */
9353e321b583ed6f2b42414257a5212885575b5cvboxsync/** Treat the value as decimal - only applicable with the RTGETOPT_REQ_*INT*. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** Mask of valid bits - for validation. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync#define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK | RTGETOPT_FLAG_HEX | RTGETOPT_FLAG_OCT | RTGETOPT_FLAG_DEC )
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * An option definition.
2a5e5a032e6f23f8937718e4ee4d6979188bdd19vboxsynctypedef struct RTOPTIONDEF
2a5e5a032e6f23f8937718e4ee4d6979188bdd19vboxsync /** The long option.
2a5e5a032e6f23f8937718e4ee4d6979188bdd19vboxsync * This is optional */
2a5e5a032e6f23f8937718e4ee4d6979188bdd19vboxsync const char *pszLong;
2a5e5a032e6f23f8937718e4ee4d6979188bdd19vboxsync /** The short option character.
2a5e5a032e6f23f8937718e4ee4d6979188bdd19vboxsync * This doesn't have to be a character, it may also be a \#define or enum value if
2a5e5a032e6f23f8937718e4ee4d6979188bdd19vboxsync * there isn't any short version of this option. */
2a5e5a032e6f23f8937718e4ee4d6979188bdd19vboxsync /** The flags (RTGETOPT_*). */
2a5e5a032e6f23f8937718e4ee4d6979188bdd19vboxsync/** Pointer to an option definition. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync/** Pointer to an const option definition. */
f62342e2cc901a67e27fa69c0e712ee35e9c4c68vboxsync * Option argument union.
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * What ends up here depends on argument format in the option definition.
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * @remarks Integers will bet put in the \a i and \a u members and sign/zero extended
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * according to the signedness indicated by the \a fFlags. So, you can choose
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * use which ever of the integer members for accessing the value regardless
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * of restrictions indicated in the \a fFlags.
cebc93936b5bb4d867e1c086dd1b206db33c31dcvboxsync /** Pointer to the definition on failure or when the option doesn't take an argument.
cebc93936b5bb4d867e1c086dd1b206db33c31dcvboxsync * This can be NULL for some errors. */
62a515eec8de1b7804ec6997c0f2013fef5c5a6bvboxsync /** A RTGETOPT_ARG_FORMAT_STRING option argument. */
cebc93936b5bb4d867e1c086dd1b206db33c31dcvboxsync const char *psz;
cebc93936b5bb4d867e1c086dd1b206db33c31dcvboxsync#if !defined(RT_ARCH_AMD64) && !defined(RT_ARCH_X86)
cebc93936b5bb4d867e1c086dd1b206db33c31dcvboxsync# error "PORTME: big-endian systems will need to fix the layout here to get the next two fields working right"
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync /** A RTGETOPT_ARG_FORMAT_INT8 option argument. */
19cb1f8699e352d590c4946caee33863a5157241vboxsync /** A RTGETOPT_ARG_FORMAT_UINT8 option argument . */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync /** A RTGETOPT_ARG_FORMAT_INT16 option argument. */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync /** A RTGETOPT_ARG_FORMAT_UINT16 option argument . */
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync /** A RTGETOPT_ARG_FORMAT_INT16 option argument. */
3933885bc0c2c93436d858a14564c6179ec72872vboxsync /** A RTGETOPT_ARG_FORMAT_UINT32 option argument . */
3933885bc0c2c93436d858a14564c6179ec72872vboxsync /** A RTGETOPT_ARG_FORMAT_INT64 option argument. */
3933885bc0c2c93436d858a14564c6179ec72872vboxsync /** A RTGETOPT_ARG_FORMAT_UINT64 option argument. */
3933885bc0c2c93436d858a14564c6179ec72872vboxsync /** A signed integer value. */
a72b5355eb89aafe6bfcc8912cf02645d7cccceavboxsync /** An unsigned integer value. */
6e25221ce8ef8e656d1e15eb7ec5cf8ae758ceb2vboxsync/** Pointer to an option argument union. */
3933885bc0c2c93436d858a14564c6179ec72872vboxsync/** Pointer to a const option argument union. */
e2760cdc84c692bc46cfaf5018d313db2f122acavboxsync * Command line argument parser, handling both long and short options and checking
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * argument formats, if desired.
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * This is to be called in a loop until it returns 0 (meaning that all options
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * were parsed) or a negative value (meaning that an error occured). The passed in
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * argument vector is sorted into options and non-option arguments, such that when
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * returning 0 the *piThis is the index of the first non-option argument.
dbabc9de5bf52ce5eb77cf82b038e9a6166c5a04vboxsync * For example, for a program which takes the following options:
4090390866c02d5d0ad061151cdb298b9a173e86vboxsync * --optwithstring (or -s) and a string argument;
40dce69ff1c2949a489337922f30f1021d62d864vboxsync * --optwithint (or -i) and a 32-bit signed integer argument;
40dce69ff1c2949a489337922f30f1021d62d864vboxsync * --verbose (or -v) with no arguments,
40dce69ff1c2949a489337922f30f1021d62d864vboxsync * code would look something like this:
7a29aa5ce149ccd344a2929d2815b8e212690b92vboxsync * int main(int argc, char *argv[])
147e101bcd061b5e085e4a2c0cc9fc35546ff1aavboxsync * static const RTOPTIONDEF s_aOptions[] =
147e101bcd061b5e085e4a2c0cc9fc35546ff1aavboxsync * { "--optwithstring", 's', RTGETOPT_REQ_STRING },
147e101bcd061b5e085e4a2c0cc9fc35546ff1aavboxsync * { "--optwithint", 'i', RTGETOPT_REQ_INT32 },
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * { "--verbose", 'v', 0 },
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * int i = 1;
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * RTOPTIONUNION ValueUnion;
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsync * while ((ch = RTGetOpt(argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), &i, &ValueUnion)))
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsync * // for options that require an argument, ValueUnion has received the value
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsync * switch (ch)
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsync * case 's': // --optwithstring or -s
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsync * // string argument, copy ValueUnion.psz
db0ecde8f28fdb4525bc6d94056166c70b02ebb8vboxsync * case 'i': // --optwithint or -i
db0ecde8f28fdb4525bc6d94056166c70b02ebb8vboxsync * // integer argument, copy ValueUnion.i32
6e12ccc60ac657fb87e27b7a2b26e0a63bebe024vboxsync * case 'v': // --verbose or -v
6e12ccc60ac657fb87e27b7a2b26e0a63bebe024vboxsync * g_fOptVerbose = true;
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * if (ch > 0)
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsync * Error("missing case: %c\n", ch);
9353e321b583ed6f2b42414257a5212885575b5cvboxsync * else if (ValueUnion.pDef)
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsync * Error("%s: %Rrs", ValueUnion.pDef->pszLong, ch);
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsync * Error("%Rrs", ch);
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsync * return 1;
1c6ec9a3a329da6f61978a372e509cd233f0d9f9vboxsync * while (i < argc)
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * //do stuff to argv[i].
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * return 0;
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * @param argc argument count, to be copied from what comes in with main().
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * @param argv argument array, to be copied from what comes in with main().
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * This may end up being modified by the option/argument sorting.
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * @param paOptions array of RTOPTIONDEF structures, which must specify what options are understood by the program.
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * @param cOptions number of array items passed in with paOptions.
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * @param piThis address of stack counter used internally by RTGetOpt; value must be initialized to 1 before the first call!
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * @param pValueUnion union with value; in the event of an error, psz member points to erroneous parameter; otherwise, for options
9e4ea89b1085fdaa5861e45a729d9c978db1a8f1vboxsync * that require an argument, this contains the value of that argument, depending on the type that is required.
261b44f7fa60a1d4bb4102142d3aa44188908484vboxsyncRTDECL(int) RTGetOpt(int argc, char **argv, PCRTOPTIONDEF paOptions, size_t cOptions, int *piThis, PRTOPTIONUNION pValueUnion);