Function rcutils_get_env

Function Documentation

const char *rcutils_get_env(const char *env_name, const char **env_value)

Retrieve the value of the given environment variable if it exists, or “”.

The c-string which is returned in the env_value output parameter is only valid until the next time this function is called, because it is a direct pointer to the static storage. The variable env_value populated by this function should never have free() called on it. If the environment variable is not set, an empty string will be returned.

In both cases, environment variable set or unset, NULL is returned unless an exception has occurred, in which case the error string is returned. For example:

#include <stdio.h>
#include <rcutils/env.h>
const char * env_value;
const char * error_str;
error_str = rcutils_get_env("SOME_ENV_VAR", &env_value);
if (error_str != NULL) {
  fprintf(stderr, "Error getting env var: %s\n", error_str);
}
printf("Valued of 'SOME_ENV_VAR': %s\n", env_value);

This function cannot be concurrently called together with rcutils_set_env (or any platform specific equivalent) on different threads, but multiple concurrent calls to this function are thread safe.

Parameters:

  • env_name – [in] the name of the environment variable

  • env_value – [out] pointer to the value cstring, or “” if unset

Returns:

NULL on success (success can be returning an empty string), or

Returns:

an error string on failure.