OpenMPI  0.1.1
opal_environ.h File Reference

Generic helper routines for environment manipulation. More...

#include "opal_config.h"

Go to the source code of this file.

Functions

BEGIN_C_DECLS OPAL_DECLSPEC char ** opal_environ_merge (char **minor, char **major) __opal_attribute_warn_unused_result__
 Merge two environ-like arrays into a single, new array, ensuring that there are no duplicate entries. More...
 
OPAL_DECLSPEC int opal_setenv (const char *name, const char *value, bool overwrite, char ***env) __opal_attribute_nonnull__(1)
 Portable version of setenv(3), allowing editing of any environ-like array. More...
 
OPAL_DECLSPEC int opal_unsetenv (const char *name, char ***env) __opal_attribute_nonnull__(1)
 Portable version of unsetenv(3), allowing editing of any environ-like array. More...
 
OPAL_DECLSPEC const char * opal_home_directory (void)
 
OPAL_DECLSPEC const char * opal_tmp_directory (void)
 

Variables

OPAL_DECLSPEC char ** environ
 

Detailed Description

Generic helper routines for environment manipulation.

Function Documentation

BEGIN_C_DECLS OPAL_DECLSPEC char** opal_environ_merge ( char **  minor,
char **  major 
)

Merge two environ-like arrays into a single, new array, ensuring that there are no duplicate entries.

Parameters
minorSet 1 of the environ's to merge
majorSet 2 of the environ's to merge
Return values
Newarray of environ

Merge two environ-like arrays into a single, new array, ensuring that there are no duplicate entires. If there are duplicates, entries in the major array are favored over those in the minor array.

Both major and minor are expected to be argv-style arrays (i.e., terminated with a NULL pointer).

The array that is returned is an unencumbered array that should later be freed with a call to opal_argv_free().

Either (or both) of major and minor can be NULL. If one of the two is NULL, the other list is simply copied to the output. If both are NULL, NULL is returned.

References opal_argv_copy(), and opal_setenv().

OPAL_DECLSPEC int opal_setenv ( const char *  name,
const char *  value,
bool  overwrite,
char ***  env 
)

Portable version of setenv(3), allowing editing of any environ-like array.

Parameters
nameString name of the environment variable to look for
valueString value to set (may be NULL)
overwriteWhether to overwrite any existing value with the same name
envThe environment to use
Return values
OPAL_ERR_OUT_OF_RESOURCEIf internal malloc() fails.
OPAL_EXISTSIf the name already exists in env and overwrite is false (and therefore the value was not saved in env)
OPAL_SUCESSIf the value replaced another value or is appended to env.

env is expected to be a NULL-terminated array of pointers (argv-style). Note that unlike some implementations of putenv(3), if value is insertted in env, it is copied. So the caller can modify/free both name and value after opal_setenv() returns.

The env array will be grown if necessary.

It is permissable to invoke this function with the system-defined environ variable. For example:

1 #include "opal/util/opal_environ.h"
2 opal_setenv("foo", "bar", true, &environ);

NOTE: If you use the real environ, opal_setenv() will turn around and perform putenv() to put the value in the environment. This may very well lead to a memory leak, so its use is strongly discouraged.

It is also permissable to call this function with an empty env, as long as it is pre-initialized with NULL:

1 char **my_env = NULL;
2 opal_setenv("foo", "bar", true, &my_env);

References opal_argv_append(), and opal_argv_count().

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

OPAL_DECLSPEC int opal_unsetenv ( const char *  name,
char ***  env 
)

Portable version of unsetenv(3), allowing editing of any environ-like array.

Parameters
nameString name of the environment variable to look for
envThe environment to use
Return values
OPAL_ERR_OUT_OF_RESOURCEIf an internal malloc fails.
OPAL_ERR_NOT_FOUNDIf name is not found in env.
OPAL_SUCCESSIf name is found and successfully deleted.

If name is found in env, the string corresponding to that entry is freed and its entry is eliminated from the array.