OpenMPI 0.1.1

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

- File List
- Globals

Functions
argv.h File Reference

Generic routines for "argv"-like handling. More...

`#include "opal_config.h"`

Go to the source code of this file.

## Functions
BEGIN_C_DECLS OPAL_DECLSPEC int | opal_argv_append (int *argc, char ***argv, const char *arg) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(3)
| Append a string (by value) to an new or existing NULL-terminated argv array. More...
OPAL_DECLSPEC int | opal_argv_append_nosize (char ***argv, const char *arg)
| Append to an argv-style array, but ignore the size of the array. More...
OPAL_DECLSPEC int | opal_argv_prepend_nosize (char ***argv, const char *arg)
| Insert the provided arg at the beginning of the array. More...
OPAL_DECLSPEC int | opal_argv_append_unique_nosize (char ***argv, const char *arg, bool overwrite)
| Append to an argv-style array, but only if the provided argument doesn't already exist somewhere in the array. More...
OPAL_DECLSPEC void | opal_argv_free (char **argv)
| Free a NULL-terminated argv array. More...
OPAL_DECLSPEC char ** | opal_argv_split (const char *src_string, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
| Split a string into a NULL-terminated argv array. More...
OPAL_DECLSPEC char ** | opal_argv_split_with_empty (const char *src_string, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
| Split a string into a NULL-terminated argv array. More...
OPAL_DECLSPEC int | opal_argv_count (char **argv)
| Return the length of a NULL-terminated argv array. More...
OPAL_DECLSPEC char * | opal_argv_join (char **argv, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
| Join all the elements of an argv array into a single newly-allocated string. More...
OPAL_DECLSPEC char * | opal_argv_join_range (char **argv, size_t start, size_t end, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
OPAL_DECLSPEC size_t | opal_argv_len (char **argv)
| Return the number of bytes consumed by an argv array. More...
OPAL_DECLSPEC char ** | opal_argv_copy (char **argv) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
| Copy a NULL-terminated argv array. More...
OPAL_DECLSPEC int | opal_argv_delete (int *argc, char ***argv, int start, int num_to_delete)
| Delete one or more tokens from the middle of an argv. More...
OPAL_DECLSPEC int | opal_argv_insert (char ***target, int start, char **source)
| Insert one argv array into the middle of another. More...
OPAL_DECLSPEC int | opal_argv_insert_element (char ***target, int location, char *source)
| Insert one argv element in front of a specific position in an array. More...

## Detailed Description

Generic routines for "argv"-like handling.

Helpful for creating arrays of strings, especially when creating command lines.

## Function Documentation

BEGIN_C_DECLS OPAL_DECLSPEC int opal_argv_append | ( | int * | argc,
|  | char *** | argv,
|  | const char * | arg
| ) |  |

Append a string (by value) to an new or existing NULL-terminated argv array.

Parameters

  argc | Pointer to the length of the argv array. Must not be NULL.
  argv | Pointer to an argv array.
  str | Pointer to the string to append.

Return values

  OPAL_SUCCESS | On success
  OPAL_ERROR | On failure

This function adds a string to an argv array of strings by value; it is permissable to pass a string on the stack as the str argument to this function.

To add the first entry to an argv array, call this function with (*argv == NULL). This function will allocate an array of length 2; the first entry will point to a copy of the string passed in arg, the second entry will be set to NULL.

If (argv != NULL), it will be realloc'ed to be 1 (char) larger, and the next-to-last entry will point to a copy of the string passed in arg. The last entry will be set to NULL.

Just to reinforce what was stated above: the string is copied by value into the argv array; there is no need to keep the original string (i.e., the arg parameter) after invoking this function.

References opal_argv_append_nosize(), and opal_argv_count().

Referenced by mca_base_param_build_env(), opal_argv_copy(), opal_argv_insert(), opal_argv_insert_element(), opal_cmd_line_get_usage_msg(), opal_cmd_line_parse(), opal_setenv(), orte_plm_base_orted_append_basic_args(), and orte_plm_submit_launch().

OPAL_DECLSPEC int opal_argv_append_nosize | ( | char *** | argv,
|  | const char * | arg
| ) |  |

Append to an argv-style array, but ignore the size of the array.

Parameters

  argv | Pointer to an argv array.
  str | Pointer to the string to append.

Return values

  OPAL_SUCCESS | On success
  OPAL_ERROR | On failure

This function is identical to the opal_argv_append() function except that it does not take a pointer to an argc (integer representing the size of the array). This is handy for argv-style arrays that do not have integers that are actively maintaing their sizes.

References opal_argv_count().

Referenced by opal_argv_append(), opal_argv_append_unique_nosize(), opal_show_help_add_dir(), and orte_odls_base_open().

OPAL_DECLSPEC int opal_argv_append_unique_nosize | ( | char *** | argv,
|  | const char * | arg,
|  | bool | overwrite
| ) |  |

Append to an argv-style array, but only if the provided argument doesn't already exist somewhere in the array.

Ignore the size of the array.

Parameters

  argv | Pointer to an argv array.
  str | Pointer to the string to append.
  bool | Whether or not to overwrite a matching value if found

Return values

  OPAL_SUCCESS | On success
  OPAL_ERROR | On failure

This function is identical to the opal_argv_append_nosize() function except that it only appends the provided argument if it does not already exist in the provided array, or overwrites it if it is.

References opal_argv_append_nosize().

Referenced by orte_ras_base_node_insert().

OPAL_DECLSPEC char** opal_argv_copy | ( | char ** | argv | ) |

Copy a NULL-terminated argv array.

Parameters

  argv | The input argv array.

Return values

  argv | Copied argv array on success.
  NULL | On failure.

Copy an argv array, including copying all off its strings. Specifically, the output argv will be an array of the same length as the input argv, and strcmp(argv_in[i], argv_out[i]) will be 0.

References opal_argv_append(), and opal_argv_free().

Referenced by mca_btl_ud_component_init(), mca_btl_udapl_component_init(), opal_cmd_line_get_tail(), opal_cmd_line_parse(), opal_environ_merge(), and orte_plm_submit_launch().

OPAL_DECLSPEC int opal_argv_count | ( | char ** | argv | ) |

Return the length of a NULL-terminated argv array.

Parameters

  argv | The input argv array.

Return values

  0 | If NULL is passed as argv.
  count | Number of entries in the argv array.

The argv array must be NULL-terminated.

Referenced by mca_io_base_delete(), mca_io_base_file_select(), mca_oob_tcp_resolve(), opal_argv_append(), opal_argv_append_nosize(), opal_argv_delete(), opal_argv_insert(), opal_argv_insert_element(), opal_argv_prepend_nosize(), opal_cmd_line_parse(), opal_os_dirpath_create(), opal_setenv(), orte_odls_base_open(), orte_plm_base_orted_append_basic_args(), orte_rmaps_base_open(), and parse_args().

OPAL_DECLSPEC int opal_argv_delete | ( | int * | argc,
|  | char *** | argv,
|  | int | start,
|  | int | num_to_delete
| ) |  |

Delete one or more tokens from the middle of an argv.

Parameters

  argv | The argv to delete from
  start | The index of the first token to delete
  num_to_delete | How many tokens to delete

Return values

  OPAL_SUCCESS | Always

Delete some tokens from within an existing argv. The start parameter specifies the first token to delete, and will delete (num_to_delete-1) tokens following it. argv will be realloc()ed to *argc - num_deleted size.

If start is beyond the end of the argv array, this function is a no-op.

If num_to_delete runs beyond the end of the argv array, this function will delete all tokens starting with start to the end of the array.

All deleted items in the argv array will have their contents free()ed (it is assumed that the argv "owns" the memory that the pointer points to).

References opal_argv_count().

Referenced by opal_cmd_line_parse().

OPAL_DECLSPEC void opal_argv_free | ( | char ** | argv | ) |

Free a NULL-terminated argv array.

Parameters

  argv | Argv array to free.

This function frees an argv array and all of the strings that it contains. Since the argv parameter is passed by value, it is not set to NULL in the caller's scope upon return.

It is safe to invoke this function with a NULL pointer. It is not safe to invoke this function with a non-NULL-terminated argv array.

Referenced by mca_base_param_build_env(), mca_btl_ud_component_init(), mca_io_base_delete(), mca_io_base_file_select(), opal_argv_copy(), opal_cmd_line_get_usage_msg(), opal_cmd_line_parse(), opal_os_dirpath_create(), opal_show_help_vstring(), orte_odls_base_open(), orte_plm_submit_launch(), and orte_rmaps_base_open().

OPAL_DECLSPEC int opal_argv_insert | ( | char *** | target,
|  | int | start,
|  | char ** | source
| ) |  |

Insert one argv array into the middle of another.

Parameters

  target | The argv to insert tokens into
  start | Index where the first token will be placed in target
  source | The argv to copy tokens from

Return values

  OPAL_SUCCESS | upon success
  OPAL_BAD_PARAM | if any parameters are non-sensical

This function takes one arg and inserts it in the middle of another. The first token in source will be insertted at index start in the target argv; all other tokens will follow it. Similar to opal_argv_append(), the target may be realloc()'ed to accomodate the new storage requirements.

The source array is left unaffected – its contents are copied by value over to the target array (i.e., the strings that source points to are strdup'ed into the new locations in target).

References opal_argv_append(), and opal_argv_count().

Referenced by opal_cmd_line_parse().

OPAL_DECLSPEC int opal_argv_insert_element | ( | char *** | target,
|  | int | location,
|  | char * | source
| ) |  |

Insert one argv element in front of a specific position in an array.

Parameters

  target | The argv to insert tokens into
  location | Index where the token will be placed in target
  source | The token to be inserted

Return values

  OPAL_SUCCESS | upon success
  OPAL_BAD_PARAM | if any parameters are non-sensical

This function takes one arg and inserts it in the middle of another. The token will be inserted at the specified index in the target argv; all other tokens will be shifted down. Similar to opal_argv_append(), the target may be realloc()'ed to accomodate the new storage requirements.

The source token is left unaffected – its contents are copied by value over to the target array (i.e., the string that source points to is strdup'ed into the new location in target).

References opal_argv_append(), and opal_argv_count().

OPAL_DECLSPEC char* opal_argv_join | ( | char ** | argv,
|  | int | delimiter
| ) |  |

Join all the elements of an argv array into a single newly-allocated string.

Parameters

  argv | The input argv array.
  delimiter | Delimiter character placed between each argv string.

Return values

  new_string | Output string on success.
  NULL | On failure.

Similar to the Perl join function, this function takes an input argv and joins them into into a single string separated by the delimiter character.

It is the callers responsibility to free the returned string.

Referenced by opal_cmd_line_get_usage_msg(), orte_plm_submit_launch(), and parse_args().

OPAL_DECLSPEC size_t opal_argv_len | ( | char ** | argv | ) |

Return the number of bytes consumed by an argv array.

Parameters

  argv | The input argv array.

Count the number of bytes consumed by a NULL-terminated argv array. This includes the number of bytes used by each of the strings as well as the pointers used in the argv array.

OPAL_DECLSPEC int opal_argv_prepend_nosize | ( | char *** | argv,
|  | const char * | arg
| ) |  |

Insert the provided arg at the beginning of the array.

Parameters

  argv | Pointer to an argv array
  str | Pointer to the string to prepend

Return values

  OPAL_SUCCESS | On success
  OPAL_ERROR | On failure

References opal_argv_count().

OPAL_DECLSPEC char** opal_argv_split | ( | const char * | src_string,
|  | int | delimiter
| ) |  |

Split a string into a NULL-terminated argv array.

Do not include empty strings in result array.

Parameters

  src_string | Input string.
  delimiter | Delimiter character.

Return values

  argv | pointer to new argv array on success
  NULL | on error

All strings are insertted into the argv array by value; the newly-allocated array makes no references to the src_string argument (i.e., it can be freed after calling this function without invalidating the output argv).

Referenced by mca_btl_base_select(), mca_btl_ud_component_init(), mca_btl_udapl_component_init(), mca_io_base_delete(), mca_io_base_file_select(), ompi_wait_for_debugger(), opal_os_dirpath_create(), orte_register_params(), orte_rmaps_base_open(), and orte_rml_base_parse_uris().

OPAL_DECLSPEC char** opal_argv_split_with_empty | ( | const char * | src_string,
|  | int | delimiter
| ) |  |

Split a string into a NULL-terminated argv array.

Include empty strings in result array.

Parameters

  src_string | Input string.
  delimiter | Delimiter character.

Return values

  argv | pointer to new argv array on success
  NULL | on error

All strings are insertted into the argv array by value; the newly-allocated array makes no references to the src_string argument (i.e., it can be freed after calling this function without invalidating the output argv).