OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

Data Structures | Typedefs | Enumerations | Functions
cmd_line.h File Reference

General command line parsing facility for use throughout Open MPI. More...

`#include "opal_config.h"`
`#include "opal/class/opal_object.h"`
`#include "opal/class/opal_list.h"`
`#include "opal/threads/mutex.h"`

Go to the source code of this file.

## Data Structures
struct | opal_cmd_line_t
struct | opal_cmd_line_init_t
| Datatype used to construct a command line handle; see opal_cmd_line_create(). More...

## Typedefs
typedef struct opal_cmd_line_t | opal_cmd_line_t
typedef enum opal_cmd_line_type_t | opal_cmd_line_type_t
typedef struct opal_cmd_line_init_t | opal_cmd_line_init_t

## Enumerations
enum | opal_cmd_line_type_t { OPAL_CMD_LINE_TYPE_NULL, OPAL_CMD_LINE_TYPE_STRING, OPAL_CMD_LINE_TYPE_INT, OPAL_CMD_LINE_TYPE_SIZE_T, OPAL_CMD_LINE_TYPE_BOOL, OPAL_CMD_LINE_TYPE_MAX }
| Data types supported by the parser.

## Functions
OPAL_DECLSPEC | OBJ_CLASS_DECLARATION (opal_cmd_line_t)
| Top-level command line handle. More...
OPAL_DECLSPEC int | opal_cmd_line_create (opal_cmd_line_t *cmd, opal_cmd_line_init_t *table)
| Make a command line handle from a table of initializers. More...
OPAL_DECLSPEC int | opal_cmd_line_make_opt_mca (opal_cmd_line_t *cmd, opal_cmd_line_init_t entry)
| Create a command line option. More...
OPAL_DECLSPEC int | opal_cmd_line_make_opt (opal_cmd_line_t *cmd, char short_name, const char *long_name, int num_params, const char *desc) __opal_attribute_deprecated__
OPAL_DECLSPEC int | opal_cmd_line_make_opt3 (opal_cmd_line_t *cmd, char short_name, const char *sd_name, const char *long_name, int num_params, const char *desc)
| Create a command line option. More...
OPAL_DECLSPEC int | opal_cmd_line_parse (opal_cmd_line_t *cmd, bool ignore_unknown, int argc, char **argv)
| Parse a command line according to a pre-built OPAL command line handle. More...
OPAL_DECLSPEC char * | opal_cmd_line_get_usage_msg (opal_cmd_line_t *cmd) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
| Return a consolidated "usage" message for a OPAL command line handle. More...
OPAL_DECLSPEC bool | opal_cmd_line_is_taken (opal_cmd_line_t *cmd, const char *opt) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(2)
| Test if a given option was taken on the parsed command line. More...
OPAL_DECLSPEC int | opal_cmd_line_get_argc (opal_cmd_line_t *cmd) __opal_attribute_unused__
| Return the number of arguments parsed on a OPAL command line handle. More...
OPAL_DECLSPEC char * | opal_cmd_line_get_argv (opal_cmd_line_t *cmd, int index)
| Return a string argument parsed on a OPAL command line handle. More...
OPAL_DECLSPEC int | opal_cmd_line_get_ninsts (opal_cmd_line_t *cmd, const char *opt) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(2)
| Return the number of instances of an option found during parsing. More...
OPAL_DECLSPEC char * | opal_cmd_line_get_param (opal_cmd_line_t *cmd, const char *opt, int instance_num, int param_num)
| Return a specific parameter for a specific instance of a option from the parsed command line. More...
OPAL_DECLSPEC int | opal_cmd_line_get_tail (opal_cmd_line_t *cmd, int *tailc, char ***tailv) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(2)
| Return the entire "tail" of unprocessed argv from a OPAL command line handle. More...

## Detailed Description

General command line parsing facility for use throughout Open MPI.

This scheme is inspired by the GNU getopt package. Command line options are registered. Each option can have up to three different matching tokens: a "short" name, a "single dash" name, and a "long" name. Each option can also take 0 or more arguments. Finally, each option can be repeated on the command line an arbitrary number of times.

The "short" name can only be a single letter, and will be found after a single dash (e.g., "-a"). Multiple "short" names can be combined into a single command line argument (e.g., "-abc" can be equivalent to "-a -b -c").

The "single dash" name is a multi-character name that only requires a single dash. This only exists to provide backwards compatibility for some well-known command line options in prior MPI implementations (e.g., "mpirun -np 3"). It should be used sparingly.

The "long" name is a multi-character name that is found after a pair of dashes. For example, "--some-option-name".

A command line option is a combination of 1 or more of a short name, single dash name, and a long name. Any of the names may be used on the command line; they are treated as synonyms. For example, say the following was used in for an executable named "foo":

opal_cmd_line_make_opt3(cmd, 'a', NULL, 'add', 1, "Add a user");

In this case, the following command lines are exactly equivalent:

    * shell$ foo -a jsmith
    * shell$ foo --add jsmith
    *

Note that this interface can also track multiple invocations of the same option. For example, the following is both legal and able to be retrieved through this interface:

    * shell$ foo -a jsmith -add bjones
    *

The caller to this interface creates a command line handle (opal_cmd_line_t) with OBJ_NEW() and then uses it to register the desired parameters via opal_cmd_line_make_opt3() (or the deprecated opal_cmd_line_make_opt()). Once all the parameters have been registered, the user invokes opal_cmd_line_parse() with the command line handle and the argv/argc pair to be parsed (typically the arguments from main()). The parser will examine the argv and find registered options and parameters. It will stop parsing when it runs into an recognized string token or the special "--" token.

After the parse has occurred, various accessor functions can be used to determine which options were selected, what parameters were passed to them, etc.:

- opal_cmd_line_get_usage_msg() returns a string suitable for "help" kinds of messages.
- opal_cmd_line_is_taken() returns a true or false indicating whether a given command line option was found on the command line.
- opal_cmd_line_get_argc() returns the number of tokens parsed on the handle.
- opal_cmd_line_get_argv() returns any particular string from the original argv.
- opal_cmd_line_get_ninsts() returns the number of times a particular option was found on a command line.
- opal_cmd_line_get_param() returns the Nth parameter in the Mth instance of a given parameter.
- opal_cmd_line_get_tail() returns an array of tokens not parsed (i.e., if the parser ran into "--" or an unrecognized token).

Note that a shortcut to creating a large number of options exists – one can make a table of opal_cmd_line_init_t instances and the table to opal_cmd_line_create(). This creates an opal_cmd_line_t handle that is pre-seeded with all the options from the table without the need to repeatedly invoke opal_cmd_line_make_opt3() (or equivalent). This opal_cmd_line_t instance is just like any other; it is still possible to add more options via opal_cmd_line_make_opt3(), etc.

## Function Documentation

OPAL_DECLSPEC OBJ_CLASS_DECLARATION | ( | opal_cmd_line_t |  | ) |

Top-level command line handle.

This handle is used for accessing all command line functionality (i.e., all opal_cmd_line*() functions). Multiple handles can be created and simultaneously processed; each handle is independant from others.

The opal_cmd_line_t handles are [simplisticly] thread safe; processing is guaranteed to be mutually exclusive if multiple threads invoke functions on the same handle at the same time – access will be serialized in an unspecified order.

Once finished, handles should be released with OBJ_RELEASE(). The destructor for opal_cmd_line_t handles will free all memory associated with the handle.

OPAL_DECLSPEC int opal_cmd_line_create | ( | opal_cmd_line_t * | cmd,
|  | opal_cmd_line_init_t * | table
| ) |  |

Make a command line handle from a table of initializers.

Parameters

  cmd | OPAL command line handle.
  table | Table of opal_cmd_line_init_t instances for all the options to be included in the resulting command line handler.

Return values

  OPAL_SUCCESS | Upon success.

This function takes a table of opal_cmd_line_init_t instances to pre-seed an OPAL command line handle. The last instance in the table must have '\0' for the short name and NULL for the single-dash and long names. The handle is expected to have been OBJ_NEW'ed or OBJ_CONSTRUCT'ed already.

Upon return, the command line handle is just like any other. A sample using this syntax:

1 opal_cmd_line_init_t cmd_line_init[] = {
2 { NULL, NULL, NULL, 'h', NULL, "help", 0,
3 &orterun_globals.help, OPAL_CMD_LINE_TYPE_BOOL,
4 "This help message" },
5
6 { NULL, NULL, NULL, '\0', NULL, "wd", 1,
7 &orterun_globals.wd, OPAL_CMD_LINE_TYPE_STRING,
8 "Set the working directory of the started processes" },
9
10 { NULL, NULL, NULL, '\0', NULL, NULL, 0,
11 NULL, OPAL_CMD_LINE_TYPE_NULL, NULL }
12 };

References OBJ_CONSTRUCT.

Referenced by parse_args().

OPAL_DECLSPEC int opal_cmd_line_get_argc | ( | opal_cmd_line_t * | cmd | ) |

Return the number of arguments parsed on a OPAL command line handle.

Parameters

  cmd | A pointer to the OPAL command line handle.

Return values

  OPAL_ERROR | If cmd is NULL.
  argc | Number of arguments previously added to the handle.

Arguments are added to the handle via the opal_cmd_line_parse() function.

References opal_cmd_line_t::lcl_argc.

OPAL_DECLSPEC char* opal_cmd_line_get_argv | ( | opal_cmd_line_t * | cmd,
|  | int | index
| ) |  |

Return a string argument parsed on a OPAL command line handle.

Parameters

  cmd | A pointer to the OPAL command line handle.
  index | The nth argument from the command line (0 is argv[0], etc.).

Return values

  NULL | If cmd is NULL or index is invalid
  argument | String of original argv[index]

This function returns a single token from the arguments parsed on this handle. Arguments are added bia the opal_cmd_line_parse() function.

What is returned is a pointer to the actual string that is on the handle; it should not be modified or freed.

References opal_cmd_line_t::lcl_argc, and opal_cmd_line_t::lcl_argv.

OPAL_DECLSPEC int opal_cmd_line_get_ninsts | ( | opal_cmd_line_t * | cmd,
|  | const char * | opt
| ) |  |

Return the number of instances of an option found during parsing.

Parameters

  cmd | OPAL command line handle.
  opt | Short or long name of the option to check for.

Return values

  num | Number of instances (to include 0) of a given potion found during opal_cmd_line_parse().
  OPAL_ERR | If the command line option was not found during opal_cmd_line_parse(), or opal_cmd_line_parse() was not invoked on this handle.

This function should only be called after opal_cmd_line_parse().

The function will return the number of instances of a given option (either by its short or long name) – to include 0 – or OPAL_ERR if either the option was not specified as part of the OPAL command line handle, or opal_cmd_line_parse() was not invoked on this handle.

References opal_cmd_line_t::lcl_mutex, opal_cmd_line_t::lcl_params, opal_list_get_end(), opal_list_get_first(), opal_list_get_next, opal_mutex_lock(), and opal_mutex_unlock().

Referenced by opal_cmd_line_is_taken().

OPAL_DECLSPEC char* opal_cmd_line_get_param | ( | opal_cmd_line_t * | cmd,
|  | const char * | opt,
|  | int | instance_num,
|  | int | param_num
| ) |  |

Return a specific parameter for a specific instance of a option from the parsed command line.

Parameters

  cmd | OPAL command line handle.
  opt | Short or long name of the option to check for.
  instance_num | Instance number of the option to query.
  param_num | Which parameter to return.

Return values

  param | String of the parameter.
  NULL | If any of the input values are invalid.

This function should only be called after opal_cmd_line_parse().

This function returns the Nth parameter for the Ith instance of a given option on the parsed command line (both N and I are zero-indexed). For example, on the command line:

executable –foo bar1 bar2 –foo bar3 bar4

The call to opal_cmd_line_get_param(cmd, "foo", 1, 1) would return "bar4". opal_cmd_line_get_param(cmd, "bar", 0, 0) would return NULL, as would opal_cmd_line_get_param(cmd, "foo", 2, 2);

The returned string should not be modified or freed by the caller.

References opal_cmd_line_t::lcl_mutex, opal_cmd_line_t::lcl_params, opal_list_get_end(), opal_list_get_first(), opal_list_get_next, opal_mutex_lock(), and opal_mutex_unlock().

OPAL_DECLSPEC int opal_cmd_line_get_tail | ( | opal_cmd_line_t * | cmd,
|  | int * | tailc,
|  | char *** | tailv
| ) |  |

Return the entire "tail" of unprocessed argv from a OPAL command line handle.

Parameters

  cmd | A pointer to the OPAL command line handle.
  tailc | Pointer to the output length of the null-terminated tail argv array.
  tailv | Pointer to the output null-terminated argv of all unprocessed arguments from the command line.

Return values

  OPAL_ERROR | If cmd is NULL or otherwise invalid.
  OPAL_SUCCESS | Upon success.

The "tail" is all the arguments on the command line that were not processed for some reason. Reasons for not processing arguments include:

See also
  The argument was not recognized
  The argument "--" was seen, and therefore all arguments following it were not processed

The output tailc parameter will be filled in with the integer length of the null-terminated tailv array (length including the final NULL entry). The output tailv parameter will be a copy of the tail parameters, and must be freed (likely with a call to opal_argv_free()) by the caller.

References opal_cmd_line_t::lcl_mutex, opal_cmd_line_t::lcl_tail_argc, opal_cmd_line_t::lcl_tail_argv, opal_argv_copy(), opal_mutex_lock(), and opal_mutex_unlock().

Referenced by parse_args().

OPAL_DECLSPEC char* opal_cmd_line_get_usage_msg | ( | opal_cmd_line_t * | cmd | ) |

Return a consolidated "usage" message for a OPAL command line handle.

Parameters

  cmd | OPAL command line handle.

Return values

  str | Usage message.

Returns a formatted string suitable for printing that lists the expected usage message and a short description of each option on the OPAL command line handle. Options that passed a NULL description to opal_cmd_line_make_opt() will not be included in the display (to allow for undocumented options).

This function is typically only invoked internally by the opal_show_help() function.

This function should probably be fixed up to produce prettier output.

The returned string must be freed by the caller.

References opal_cmd_line_t::lcl_mutex, opal_cmd_line_t::lcl_options, opal_argv_append(), opal_argv_free(), opal_argv_join(), opal_list_get_end(), opal_list_get_first(), opal_list_get_next, opal_list_get_size(), opal_mutex_lock(), and opal_mutex_unlock().

Referenced by parse_args().

OPAL_DECLSPEC bool opal_cmd_line_is_taken | ( | opal_cmd_line_t * | cmd,
|  | const char * | opt
| ) |  |

Test if a given option was taken on the parsed command line.

Parameters

  cmd | OPAL command line handle.
  opt | Short or long name of the option to check for.

Return values

  true | If the command line option was found during opal_cmd_line_parse().
  false | If the command line option was not found during opal_cmd_line_parse(), or opal_cmd_line_parse() was not invoked on this handle.

This function should only be called after opal_cmd_line_parse().

The function will return true if the option matching opt was found (either by its short or long name) during token parsing. Otherwise, it will return false.

References opal_cmd_line_get_ninsts().

OPAL_DECLSPEC int opal_cmd_line_make_opt | ( | opal_cmd_line_t * | cmd,
|  | char | short_name,
|  | const char * | long_name,
|  | int | num_params,
|  | const char * | desc
| ) |  |

Deprecated:

Create a command line option.

This function is an older [deprecated] form of opal_cmd_line_make_opt3(). It is exactly equivalent to opal_cmd_line_make_opt3(cmd, short_name, NULL, long_name, num_params, desc).

References opal_cmd_line_init_t::ocl_cmd_long_name, opal_cmd_line_init_t::ocl_cmd_short_name, opal_cmd_line_init_t::ocl_cmd_single_dash_name, opal_cmd_line_init_t::ocl_description, opal_cmd_line_init_t::ocl_mca_component_name, opal_cmd_line_init_t::ocl_mca_param_name, opal_cmd_line_init_t::ocl_mca_type_name, opal_cmd_line_init_t::ocl_num_params, opal_cmd_line_init_t::ocl_variable_dest, and opal_cmd_line_init_t::ocl_variable_type.

OPAL_DECLSPEC int opal_cmd_line_make_opt3 | ( | opal_cmd_line_t * | cmd,
|  | char | short_name,
|  | const char * | sd_name,
|  | const char * | long_name,
|  | int | num_params,
|  | const char * | desc
| ) |  |

Create a command line option.

Parameters

  cmd | OPAL command line handle.
  short_name | "Short" name of the command line option.
  sd_name | "Single dash" name of the command line option.
  long_name | "Long" name of the command line option.
  num_params | How many parameters this option takes.
  dest | Short string description of this option.

Return values

  OPAL_ERR_OUT_OF_RESOURCE | If out of memory.
  OPAL_ERR_BAD_PARAM | If bad parameters passed.
  OPAL_SUCCESS | Upon success.

Adds a command line option to the list of options that a a OPAL command line handle will accept. The short_name may take the special value '\0' to not have a short name. Likewise, the sd_name and long_name may take the special value NULL to not have a single dash or long name, respectively. However, one of the three must have a name.

num_params indicates how many parameters this option takes. It must be greater than or equal to 0.

Finally, desc is a short string description of this option. It is used to generate the output from opal_cmd_line_get_usage_msg().

References opal_cmd_line_init_t::ocl_cmd_long_name, opal_cmd_line_init_t::ocl_cmd_short_name, opal_cmd_line_init_t::ocl_cmd_single_dash_name, opal_cmd_line_init_t::ocl_description, opal_cmd_line_init_t::ocl_mca_component_name, opal_cmd_line_init_t::ocl_mca_param_name, opal_cmd_line_init_t::ocl_mca_type_name, opal_cmd_line_init_t::ocl_num_params, opal_cmd_line_init_t::ocl_variable_dest, and opal_cmd_line_init_t::ocl_variable_type.

OPAL_DECLSPEC int opal_cmd_line_make_opt_mca | ( | opal_cmd_line_t * | cmd,
|  | opal_cmd_line_init_t | entry
| ) |  |

Create a command line option.

Parameters

  cmd | OPAL command line handle.
  entry | Command line entry to add to the command line.

Return values

  OPAL_SUCCESS | Upon success.

References opal_cmd_line_init_t::ocl_cmd_long_name, opal_cmd_line_init_t::ocl_cmd_short_name, and opal_cmd_line_init_t::ocl_cmd_single_dash_name.

OPAL_DECLSPEC int opal_cmd_line_parse | ( | opal_cmd_line_t * | cmd,
|  | bool | ignore_unknown,
|  | int | argc,
|  | char ** | argv
| ) |  |

Parse a command line according to a pre-built OPAL command line handle.

Parameters

  cmd | OPAL command line handle.
  ignore_unknown | Whether to print an error message upon finding an unknown token or not
  argc | Length of the argv array.
  argv | Array of strings from the command line.

Return values

  OPAL_SUCCESS | Upon success.
  OPAL_ERR_SILENT | If an error message was printed. This value will only be returned if the command line was not successfully parsed.

Parse a series of command line tokens according to the option descriptions from a OPAL command line handle. The OPAL command line handle can then be queried to see what options were used, what their parameters were, etc.

If an unknown token is found in the command line (i.e., a token that is not a parameter or a registered option), the parsing will stop (see below). If ignore_unknown is false, an error message is displayed. If ignore_unknown is true, the error message is not displayed.

Error messages are always displayed (to stderr, and OPAL_ERR_SILENT is returned) if a token was encountered that required N parameters, but <N parameters were found (e.g., "cmd --param foo", but –param was registered to require 2 option tokens).

The contents of argc and argv are not changed during parsing. argv[0] is assumed to be the executable name, and is ignored during parsing, except when printing error messages.

Parsing will stop in the following conditions:

- all argv tokens are processed
- the token "--" is found
- an unrecognized token is found
- a parameter registered with an integer type option finds a non-integer option token
- a parameted registered N option tokens, but finds less then <N tokens available

Upon any of these conditions, any remaining tokens will be placed in the "tail" (and therefore not examined by the parser), regardless of the value of ignore_unknown. The set of tail tokens is available from the opal_cmd_line_get_tail() function.

Note that "--" is ignored if it is found in the middle an expected number of arguments. For example, if "--foo" is expected to have 3 arguments, and the command line is:

executable –foo a b – other arguments

This will result in an error, because "--" will be parsed as the third parameter to the first instance of "foo", and "other" will be an unrecognized option.

Invoking this function multiple times on different sets of argv tokens is safe, but will erase any previous parsing results.

References opal_cmd_line_t::lcl_argc, opal_cmd_line_t::lcl_argv, opal_cmd_line_t::lcl_mutex, opal_cmd_line_t::lcl_params, opal_cmd_line_t::lcl_tail_argc, opal_cmd_line_t::lcl_tail_argv, OBJ_RELEASE, opal_argv_append(), opal_argv_copy(), opal_argv_count(), opal_argv_delete(), opal_argv_free(), opal_argv_insert(), opal_list_append, opal_mutex_lock(), and opal_mutex_unlock().

Referenced by parse_args().