get_env.h File Reference

#include "rcutils/macros.h"
#include "rcutils/visibility_control.h"

Include dependency graph for get_env.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
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 "". More...
const char *	rcutils_get_home_dir (void)
	Retrieve the full path to the home directory. More...

Function Documentation

rcutils_get_env()

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/get_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

[in]	env_name	the name of the environment variable
[out]	env_value	pointer to the value cstring, or "" if unset

Returns

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

an error string on failure.

rcutils_get_home_dir()

const char* rcutils_get_home_dir

(

void

)

Retrieve the full path to the home directory.

The c-string which is returned is only valid until the next time this function is called, because it is a direct pointer to the static storage. Also note that the string returned here should not be freed.

The function first tries to get the HOME environment variable. If that variable exists and is non-empty, that will be returned. Otherwise, the function tries to get the USERPROFILE environment variable. If that variable exists and is non-empty, that will be returned. If neither exists, NULL will be returned. The above algorithm is portable across both Unix and Windows.

This function cannot be thread-safely called together with rcutils_set_env (or any platform specific equivalent), but multiple calls to this function are thread safe.

Returns

The home directory on success, or

NULL on failure.