parseopt.c File Reference

Command line option parsing. More...

#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <errno.h>
#include <getopt.h>
#include <ipxe/uuid.h>
#include <ipxe/netdevice.h>
#include <ipxe/dynui.h>
#include <ipxe/settings.h>
#include <ipxe/params.h>
#include <ipxe/timer.h>
#include <ipxe/keys.h>
#include <ipxe/parseopt.h>
#include <config/branding.h>

Go to the source code of this file.

Macros
#define	ECANCELED_NO_OP   __einfo_error ( EINFO_ECANCELED_NO_OP )
	Return status code for "--help" option. More...
#define	EINFO_ECANCELED_NO_OP   __einfo_uniqify ( EINFO_ECANCELED, 0x01, "Nothing to do" )
#define	EINVAL_INTEGER   __einfo_error ( EINFO_EINVAL_INTEGER )
#define	EINFO_EINVAL_INTEGER   __einfo_uniqify ( EINFO_EINVAL, 0x01, "Invalid integer value" )
#define	EINVAL_UNKNOWN_OPTION   __einfo_error ( EINFO_EINVAL_UNKNOWN_OPTION )
#define	EINFO_EINVAL_UNKNOWN_OPTION   __einfo_uniqify ( EINFO_EINVAL, 0x02, "Unrecognised option" )
#define	EINVAL_MISSING_ARGUMENT   __einfo_error ( EINFO_EINVAL_MISSING_ARGUMENT )
#define	EINFO_EINVAL_MISSING_ARGUMENT   __einfo_uniqify ( EINFO_EINVAL, 0x03, "Missing argument" )

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
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 **value)
	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.c.

Macro Definition Documentation

ECANCELED_NO_OP

#define ECANCELED_NO_OP   __einfo_error ( EINFO_ECANCELED_NO_OP )

Return status code for "--help" option.

Definition at line 52 of file parseopt.c.

EINFO_ECANCELED_NO_OP

#define EINFO_ECANCELED_NO_OP   __einfo_uniqify ( EINFO_ECANCELED, 0x01, "Nothing to do" )

Definition at line 53 of file parseopt.c.

EINVAL_INTEGER

#define EINVAL_INTEGER   __einfo_error ( EINFO_EINVAL_INTEGER )

Definition at line 57 of file parseopt.c.

EINFO_EINVAL_INTEGER

#define EINFO_EINVAL_INTEGER   __einfo_uniqify ( EINFO_EINVAL, 0x01, "Invalid integer value" )

Definition at line 58 of file parseopt.c.

EINVAL_UNKNOWN_OPTION

#define EINVAL_UNKNOWN_OPTION   __einfo_error ( EINFO_EINVAL_UNKNOWN_OPTION )

Definition at line 60 of file parseopt.c.

EINFO_EINVAL_UNKNOWN_OPTION

#define EINFO_EINVAL_UNKNOWN_OPTION   __einfo_uniqify ( EINFO_EINVAL, 0x02, "Unrecognised option" )

Definition at line 61 of file parseopt.c.

EINVAL_MISSING_ARGUMENT

#define EINVAL_MISSING_ARGUMENT   __einfo_error ( EINFO_EINVAL_MISSING_ARGUMENT )

Definition at line 63 of file parseopt.c.

EINFO_EINVAL_MISSING_ARGUMENT

#define EINFO_EINVAL_MISSING_ARGUMENT   __einfo_uniqify ( EINFO_EINVAL, 0x03, "Missing argument" )

Definition at line 64 of file parseopt.c.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

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 74 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 92 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 115 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 136 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 159 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 181 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 204 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 227 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 242 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 272 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 297 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 323 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 337 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 349 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 371 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 402 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 485 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().