OpenMPI  0.1.1
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
argcPointer to the length of the argv array. Must not be NULL.
argvPointer to an argv array.
strPointer to the string to append.
Return values
OPAL_SUCCESSOn success
OPAL_ERROROn 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
argvPointer to an argv array.
strPointer to the string to append.
Return values
OPAL_SUCCESSOn success
OPAL_ERROROn 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
argvPointer to an argv array.
strPointer to the string to append.
boolWhether or not to overwrite a matching value if found
Return values
OPAL_SUCCESSOn success
OPAL_ERROROn 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
argvThe input argv array.
Return values
argvCopied argv array on success.
NULLOn 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
argvThe input argv array.
Return values
0If NULL is passed as argv.
countNumber 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
argvThe argv to delete from
startThe index of the first token to delete
num_to_deleteHow many tokens to delete
Return values
OPAL_SUCCESSAlways

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
argvArgv 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
targetThe argv to insert tokens into
startIndex where the first token will be placed in target
sourceThe argv to copy tokens from
Return values
OPAL_SUCCESSupon success
OPAL_BAD_PARAMif 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
targetThe argv to insert tokens into
locationIndex where the token will be placed in target
sourceThe token to be inserted
Return values
OPAL_SUCCESSupon success
OPAL_BAD_PARAMif 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
argvThe input argv array.
delimiterDelimiter character placed between each argv string.
Return values
new_stringOutput string on success.
NULLOn 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
argvThe 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
argvPointer to an argv array
strPointer to the string to prepend
Return values
OPAL_SUCCESSOn success
OPAL_ERROROn 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_stringInput string.
delimiterDelimiter character.
Return values
argvpointer to new argv array on success
NULLon 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_stringInput string.
delimiterDelimiter character.
Return values
argvpointer to new argv array on success
NULLon 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).