parseopt.h File Reference

Command line option parsing. More...

#include <stdint.h>
#include <stddef.h>
#include <ipxe/uuid.h>
#include <ipxe/settings.h>

Go to the source code of this file.

Data Structures
struct	option_descriptor
	A command-line option descriptor. More...
struct	command_descriptor
	A command descriptor. More...
struct	named_setting
	A parsed named setting. More...
struct	uuid_option
	A UUID command-line option. More...

Macros
#define	OPTION_PARSER(_struct, _field, _parse)
	Construct option parser. More...
#define	OPTION_DESC(_longopt, _shortopt, _has_arg, _struct, _field, _parse)
	Construct option descriptor. More...
#define	MAX_ARGUMENTS   0xff
	No maximum number of arguments. More...
#define	COMMAND_DESC(_struct, _options, _min_args, _max_args, _usage)
	Construct command descriptor. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
int	parse_string (char *text, char **value)
	Parse string value. More...
int	parse_integer (char *text, unsigned int *value)
	Parse integer value. More...
int	parse_timeout (char *text, unsigned long *value)
	Parse timeout value (in ms) More...
int	parse_uuid (char *text, struct uuid_option *uuid)
	Parse UUID. More...
int	parse_netdev (char *text, struct net_device **netdev)
	Parse network device name. More...
int	parse_netdev_configurator (char *text, struct net_device_configurator **configurator)
	Parse network device configurator name. More...
int	parse_dynui (char *text, struct dynamic_ui **dynui)
	Parse dynamic user interface name. More...
int	parse_flag (char *text __unused, int *flag)
	Parse flag. More...
int	parse_key (char *text, unsigned int *key)
	Parse key. More...
int	parse_settings (char *text, struct settings **settings)
	Parse settings block name. More...
int	parse_setting (char *text, struct named_setting *setting, get_child_settings_t get_child)
	Parse setting name. More...
int	parse_existing_setting (char *text, struct named_setting *setting)
	Parse existing setting name. More...
int	parse_autovivified_setting (char *text, struct named_setting *setting)
	Parse and autovivify setting name. More...
int	parse_parameters (char *text, struct parameters **params)
	Parse request parameter list name. More...
void	print_usage (struct command_descriptor *cmd, char **argv)
	Print command usage message. More...
int	reparse_options (int argc, char **argv, struct command_descriptor *cmd, void *opts)
	Reparse command-line options. More...
int	parse_options (int argc, char **argv, struct command_descriptor *cmd, void *opts)
	Parse command-line options. More...

Detailed Description

Command line option parsing.

Definition in file parseopt.h.

Macro Definition Documentation

OPTION_PARSER

#define OPTION_PARSER	(		_struct,
			_field,
			_parse
	)

Value:

( ( int ( * ) ( char *text, void *value ) )                           \
          ( ( ( ( typeof ( _parse ) * ) NULL ) ==                             \
              ( ( int ( * ) ( char *text,                                     \
                              typeof ( ( ( _struct * ) NULL )->_field ) * ) ) \
                NULL ) ) ? _parse : _parse ) )

Construct option parser.

Parameters

_struct	Options structure type
_field	Field within options structure
_parse	Field type-specific option parser

Return values

_parse

Generic option parser

Definition at line 49 of file parseopt.h.

OPTION_DESC

#define OPTION_DESC	(		_longopt,
			_shortopt,
			_has_arg,
			_struct,
			_field,
			_parse
	)

Value:

{                                                                     \
                .longopt = _longopt,                                          \
                .shortopt = _shortopt,                                        \
                .has_arg = _has_arg,                                          \
                .offset = offsetof ( _struct, _field ),                       \
                .parse = OPTION_PARSER ( _struct, _field, _parse ),           \
        }

Construct option descriptor.

Parameters

_longopt	Long option name, if any
_shortopt	Short option name, if any
_has_arg	Argument requirement
_struct	Options structure type
_field	Field within options structure
_parse	Field type-specific option parser

Return values

_option

Option descriptor

Definition at line 67 of file parseopt.h.

MAX_ARGUMENTS

#define MAX_ARGUMENTS   0xff

No maximum number of arguments.

Definition at line 97 of file parseopt.h.

COMMAND_DESC

#define COMMAND_DESC	(		_struct,
			_options,
			_min_args,
			_max_args,
			_usage
	)

Value:

{                                                                     \
                .options = ( ( ( ( typeof ( _options[0] ) * ) NULL ) ==       \
                               ( ( struct option_descriptor * ) NULL ) ) ?    \
                             _options : _options ),                           \
                .num_options = ( sizeof ( _options ) /                        \
                                 sizeof ( _options[0] ) ),                    \
                .len = sizeof ( _struct ),                                    \
                .min_args = _min_args,                                        \
                .max_args = _max_args,                                        \
                .usage = _usage,                                              \
         }

Construct command descriptor.

Parameters

_struct	Options structure type
_options	Option descriptor array
_check_args	Remaining argument checker
_usage	Command usage

Return values

_command

Command descriptor

Definition at line 108 of file parseopt.h.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

parse_string()

int parse_string	(	char *	text,
		char **	value
	)

Parse string value.

Parameters

text

Text

Return values

value	String value
rc	Return status code

Definition at line 73 of file parseopt.c.

                                              {

        /* Sanity check */
        assert ( text != NULL );

        /* Parse string */
        *value = text;

        return 0;
}

References assert(), NULL, and value.

parse_integer()

int parse_integer	(	char *	text,
		unsigned int *	value
	)

Parse integer value.

Parameters

text

Text

Return values

value	Integer value
rc	Return status code

Definition at line 91 of file parseopt.c.

                                                      {
        char *endp;

        /* Sanity check */
        assert ( text != NULL );

        /* Parse integer */
        *value = strtoul ( text, &endp, 0 );
        if ( *endp || ( ! *text ) ) {
                printf ( "\"%s\": invalid integer value\n", text );
                return -EINVAL_INTEGER;
        }

        return 0;
}

References assert(), EINVAL_INTEGER, NULL, printf(), strtoul(), and value.

Referenced by colour_exec(), cpair_exec(), cpuid_exec(), exit_exec(), imgmem_exec(), inc_exec(), parse_key(), parse_timeout(), pxebs_exec(), and sleep_exec().

parse_timeout()

int parse_timeout	(	char *	text,
		unsigned long *	value
	)

Parse timeout value (in ms)

Parameters

text

Text

Return values

value	Integer value
rc	Return status code

Definition at line 114 of file parseopt.c.

                                                       {
        unsigned int value_ms;
        int rc;

        /* Parse raw integer value */
        if ( ( rc = parse_integer ( text, &value_ms ) ) != 0 )
                return rc;

        /* Convert to a number of timer ticks */
        *value = ( value_ms * TICKS_PER_MS );

        return 0;
}

References parse_integer(), rc, TICKS_PER_MS, and value.

parse_uuid()

int parse_uuid	(	char *	text,
		struct uuid_option *	uuid
	)

Parse UUID.

Parameters

text

Text

Return values

uuid	UUID value
rc	Return status code

Definition at line 135 of file parseopt.c.

                                                        {
        int rc;

        /* Sanity check */
        assert ( text != NULL );

        /* Parse UUID */
        if ( ( rc = uuid_aton ( text, &uuid->buf ) ) != 0 ) {
                printf ( "\"%s\": invalid UUID\n", text );
                return rc;
        }
        uuid->value = &uuid->buf;

        return 0;
}

References assert(), NULL, printf(), rc, and uuid_aton().

parse_netdev()

int parse_netdev	(	char *	text,
		struct net_device **	netdev
	)

Parse network device name.

Parameters

text

Text

Return values

netdev	Network device
rc	Return status code

Definition at line 158 of file parseopt.c.

                                                            {

        /* Sanity check */
        assert ( text != NULL );

        /* Find network device */
        *netdev = find_netdev ( text );
        if ( ! *netdev ) {
                printf ( "\"%s\": no such network device\n", text );
                return -ENODEV;
        }

        return 0;
}

References assert(), ENODEV, find_netdev(), netdev, NULL, and printf().

Referenced by ifcommon_exec(), lotest_exec(), pxebs_exec(), vcreate_exec(), and vdestroy_exec().

parse_netdev_configurator()

int parse_netdev_configurator	(	char *	text,
		struct net_device_configurator **	configurator
	)

Parse network device configurator name.

Parameters

text

Text

Return values

configurator	Network device configurator
rc	Return status code

Definition at line 180 of file parseopt.c.

                                                                               {

        /* Sanity check */
        assert ( text != NULL );

        /* Find network device configurator */
        *configurator = find_netdev_configurator ( text );
        if ( ! *configurator ) {
                printf ( "\"%s\": no such configurator\n", text );
                return -ENOTSUP;
        }

        return 0;
}

References assert(), ENOTSUP, find_netdev_configurator(), NULL, and printf().

parse_dynui()

int parse_dynui	(	char *	text,
		struct dynamic_ui **	dynui
	)

Parse dynamic user interface name.

Parameters

text

Text

Return values

dynui	Dynamic user interface
rc	Return status code

Definition at line 203 of file parseopt.c.

                                                          {

        /* Find user interface */
        *dynui = find_dynui ( text );
        if ( ! *dynui ) {
                if ( text ) {
                        printf ( "\"%s\": no such user interface\n", text );
                } else {
                        printf ( "No default user interface\n" );
                }
                return -ENOENT;
        }

        return 0;
}

References ENOENT, find_dynui(), and printf().

Referenced by choose_exec(), item_exec(), and present_exec().

parse_flag()

int parse_flag	(	char *text	__unused,
		int *	flag
	)

Parse flag.

Parameters

text	Text (ignored)

Return values

flag	Flag to set
rc	Return status code

Definition at line 226 of file parseopt.c.

                                                  {

        /* Set flag */
        *flag = 1;

        return 0;
}

References flag.

parse_key()

int parse_key	(	char *	text,
		unsigned int *	key
	)

Parse key.

Parameters

text

Text

Return values

key	Key
rc	Return status code

Definition at line 241 of file parseopt.c.

                                                {
        int rc;

        /* Interpret single characters as being a literal key character */
        if ( text[0] && ! text[1] ) {
                *key = text[0];
                return 0;
        }

        /* Otherwise, interpret as an integer */
        if ( ( rc = parse_integer ( text, key ) ) < 0 )
                return rc;

        /* For backwards compatibility with existing scripts, treat
         * integers between the ASCII range and special key range as
         * being relative special key values.
         */
        if ( ( ! isascii ( *key ) ) && ( *key < KEY_MIN ) )
                *key += KEY_MIN;

        return 0;
}

References isascii(), key, KEY_MIN, parse_integer(), and rc.

parse_settings()

int parse_settings	(	char *	text,
		struct settings **	value
	)

Parse settings block name.

Parameters

text

Text

Return values

value	Integer value
rc	Return status code

Definition at line 271 of file parseopt.c.

                                                           {

        /* Sanity check */
        assert ( text != NULL );

        /* Parse scope name */
        *value = find_settings ( text );
        if ( ! *value ) {
                printf ( "\"%s\": no such scope\n", text );
                return -EINVAL;
        }

        return 0;
}

References assert(), EINVAL, find_settings(), NULL, printf(), and value.

Referenced by config_exec().

parse_setting()

int parse_setting	(	char *	text,
		struct named_setting *	setting,
		get_child_settings_t	get_child
	)

Parse setting name.

Parameters

text	Text
setting	Named setting to fill in
get_child	Function to find or create child settings block

Return values

rc	Return status code

Note that this function modifies the original text.

Definition at line 296 of file parseopt.c.

                                                     {
        int rc;

        /* Sanity check */
        assert ( text != NULL );

        /* Parse setting name */
        if ( ( rc = parse_setting_name ( text, get_child, &setting->settings,
                                         &setting->setting ) ) != 0 ) {
                printf ( "\"%s\": invalid setting\n", text );
                return rc;
        }

        return 0;
}

References assert(), NULL, parse_setting_name(), printf(), and rc.

Referenced by parse_autovivified_setting(), and parse_existing_setting().

parse_existing_setting()

int parse_existing_setting	(	char *	text,
		struct named_setting *	setting
	)

Parse existing setting name.

Parameters

text	Text
setting	Named setting to fill in

Return values

rc	Return status code

Note that this function modifies the original text.

Definition at line 322 of file parseopt.c.

                                                                         {

        return parse_setting ( text, setting, find_child_settings );
}

References find_child_settings(), and parse_setting().

Referenced by inc_exec(), and show_exec().

parse_autovivified_setting()

int parse_autovivified_setting	(	char *	text,
		struct named_setting *	setting
	)

Parse and autovivify setting name.

Parameters

text	Text
setting	Named setting to fill in

Return values

rc	Return status code

Note that this function modifies the original text.

Definition at line 336 of file parseopt.c.

                                                                             {

        return parse_setting ( text, setting, autovivify_child_settings );
}

References autovivify_child_settings(), and parse_setting().

Referenced by choose_exec(), pciscan_exec(), set_core_exec(), and usbscan_exec().

parse_parameters()

int parse_parameters	(	char *	text,
		struct parameters **	params
	)

Parse request parameter list name.

Parameters

text

Text

Return values

params	Parameter list
rc	Return status code

Definition at line 348 of file parseopt.c.

                                                                {

        /* Find parameter list */
        *params = find_parameters ( text );
        if ( ! *params ) {
                if ( text ) {
                        printf ( "\"%s\": no such parameter list\n", text );
                } else {
                        printf ( "No default parameter list\n" );
                }
                return -ENOENT;
        }

        return 0;
}

References ENOENT, find_parameters(), and printf().

Referenced by param_exec().

print_usage()

void print_usage	(	struct command_descriptor *	cmd,
		char **	argv
	)

Print command usage message.

Parameters

cmd	Command descriptor
argv	Argument list

Definition at line 370 of file parseopt.c.

                                                                 {
        struct option_descriptor *option;
        unsigned int i;
        int is_optional;

        printf ( "Usage:\n\n  %s", argv[0] );
        for ( i = 0 ; i < cmd->num_options ; i++ ) {
                option = &cmd->options[i];
                printf ( " [-%c|--%s", option->shortopt, option->longopt );
                if ( option->has_arg ) {
                        is_optional = ( option->has_arg == optional_argument );
                        printf ( " %s<%s>%s", ( is_optional ? "[" : "" ),
                                 option->longopt, ( is_optional ? "]" : "" ) );
                }
                printf ( "]" );
        }
        if ( cmd->usage )
                printf ( " %s", cmd->usage );
        printf ( "\n\nSee " PRODUCT_COMMAND_URI " for further information\n",
                 argv[0] );
}

References cmd, option::has_arg, optional_argument, printf(), and PRODUCT_COMMAND_URI.

Referenced by reparse_options().

reparse_options()

int reparse_options	(	int	argc,
		char **	argv,
		struct command_descriptor *	cmd,
		void *	opts
	)

Reparse command-line options.

Parameters

argc	Argument count
argv	Argument list
cmd	Command descriptor
opts	Options (already initialised with default values)

Return values

rc	Return status code

Definition at line 401 of file parseopt.c.

                                   {
        struct option longopts[ cmd->num_options + 1 /* help */ + 1 /* end */ ];
        char shortopts[ cmd->num_options * 3 /* possible "::" */ + 1 /* "h" */
                        + 1 /* NUL */ ];
        unsigned int shortopt_idx = 0;
        int ( * parse ) ( char *text, void *value );
        void *value;
        unsigned int i;
        unsigned int j;
        unsigned int num_args;
        int c;
        int rc;

        /* Construct long and short option lists for getopt_long() */
        memset ( longopts, 0, sizeof ( longopts ) );
        for ( i = 0 ; i < cmd->num_options ; i++ ) {
                longopts[i].name = cmd->options[i].longopt;
                longopts[i].has_arg = cmd->options[i].has_arg;
                longopts[i].val = cmd->options[i].shortopt;
                shortopts[shortopt_idx++] = cmd->options[i].shortopt;
                assert ( cmd->options[i].has_arg <= optional_argument );
                for ( j = cmd->options[i].has_arg ; j > 0 ; j-- )
                        shortopts[shortopt_idx++] = ':';
        }
        longopts[i].name = "help";
        longopts[i].val = 'h';
        shortopts[shortopt_idx++] = 'h';
        shortopts[shortopt_idx++] = '\0';
        assert ( shortopt_idx <= sizeof ( shortopts ) );
        DBGC ( cmd,  "Command \"%s\" has options \"%s\", %d-%d args, len %d\n",
               argv[0], shortopts, cmd->min_args, cmd->max_args, cmd->len );

        /* Parse options */
        while ( ( c = getopt_long ( argc, argv, shortopts, longopts,
                                    NULL ) ) >= 0 ) {
                switch ( c ) {
                case 'h' :
                        /* Print help */
                        print_usage ( cmd, argv );
                        return -ECANCELED_NO_OP;
                case '?' :
                        /* Print usage message */
                        print_usage ( cmd, argv );
                        return -EINVAL_UNKNOWN_OPTION;
                case ':' :
                        /* Print usage message */
                        print_usage ( cmd, argv );
                        return -EINVAL_MISSING_ARGUMENT;
                default:
                        /* Search for an option to parse */
                        for ( i = 0 ; i < cmd->num_options ; i++ ) {
                                if ( c != cmd->options[i].shortopt )
                                        continue;
                                parse = cmd->options[i].parse;
                                value = ( opts + cmd->options[i].offset );
                                if ( ( rc = parse ( optarg, value ) ) != 0 )
                                        return rc;
                                break;
                        }
                        assert ( i < cmd->num_options );
                }
        }

        /* Check remaining arguments */
        num_args = ( argc - optind );
        if ( ( num_args < cmd->min_args ) || ( num_args > cmd->max_args ) ) {
                print_usage ( cmd, argv );
                return -ERANGE;
        }

        return 0;
}

References assert(), cmd, DBGC, ECANCELED_NO_OP, EINVAL_MISSING_ARGUMENT, EINVAL_UNKNOWN_OPTION, ERANGE, getopt_long(), option::has_arg, memset(), option::name, NULL, optarg, optind, optional_argument, opts, print_usage(), rc, option::val, and value.

Referenced by colour_exec(), cpair_exec(), parse_options(), ping_exec(), and sanboot_core_exec().

parse_options()

int parse_options	(	int	argc,
		char **	argv,
		struct command_descriptor *	cmd,
		void *	opts
	)

Parse command-line options.

Parameters

argc	Argument count
argv	Argument list
cmd	Command descriptor
opts	Options (may be uninitialised)

Return values

rc	Return status code

Definition at line 484 of file parseopt.c.

                                 {

        /* Clear options */
        memset ( opts, 0, cmd->len );

        return reparse_options ( argc, argv, cmd, opts );
}

References cmd, memset(), opts, and reparse_options().

Referenced by cert_exec(), choose_exec(), config_exec(), console_exec(), cpuid_exec(), digest_exec(), dynui_exec(), echo_exec(), exit_exec(), fcels_exec(), fcstat_exec(), fdt_exec(), gdbstub_exec(), goto_exec(), ibstat_exec(), ifcommon_exec(), imgdecrypt_exec(), imgextract_exec(), imgmem_exec(), imgmulti_exec(), imgsingle_exec(), imgtrust_exec(), imgverify_exec(), inc_exec(), ipstat_exec(), iseq_exec(), isset_exec(), item_exec(), login_exec(), lotest_exec(), nslookup_exec(), nstat_exec(), ntp_exec(), param_exec(), params_exec(), pciscan_exec(), poweroff_exec(), present_exec(), profstat_exec(), prompt_exec(), pxebs_exec(), reboot_exec(), route_exec(), set_core_exec(), shell_exec(), shim_exec(), show_exec(), sleep_exec(), stoppxe_exec(), sync_exec(), time_exec(), usbscan_exec(), vcreate_exec(), and vdestroy_exec().