rcutils  master
C API providing common utilities and data structures.
get_env.h
Go to the documentation of this file.
1 // Copyright 2017 Open Source Robotics Foundation, Inc.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef RCUTILS__GET_ENV_H_
16 #define RCUTILS__GET_ENV_H_
17 
18 #if __cplusplus
19 extern "C"
20 {
21 #endif
22 
23 #include "rcutils/macros.h"
25 
27 /* The c-string which is returned in the env_value output parameter is only
28  * valid until the next time this function is called, because it is a direct
29  * pointer to the static storage.
30  * The variable env_value populated by this function should never have free()
31  * called on it.
32  * If the environment variable is not set, an empty string will be returned.
33  *
34  * In both cases, environment variable set or unset, NULL is returned unless
35  * an exception has occurred, in which case the error string is returned.
36  * For example:
37  *
38  * ```c
39  * #include <stdio.h>
40  * #include <rcutils/get_env.h>
41  * const char * env_value;
42  * const char * error_str;
43  * error_str = rcutils_get_env("SOME_ENV_VAR", &env_value);
44  * if (error_str != NULL) {
45  * fprintf(stderr, "Error getting env var: %s\n", error_str);
46  * }
47  * printf("Valued of 'SOME_ENV_VAR': %s\n", env_value);
48  * ```
49  *
50  * Environment variables will be truncated at 2048 characters on Windows.
51  *
52  * This function is not thread-safe.
53  *
54  * \param[in] env_name the name of the environment variable
55  * \param[out] env_value pointer to the value cstring, or "" if unset
56  * \return NULL on success (success can be returning an empty string)
57  * error string on failure
58  */
61 const char *
62 rcutils_get_env(const char * env_name, const char ** env_value);
63 
64 #if __cplusplus
65 }
66 #endif
67 
68 #endif // RCUTILS__GET_ENV_H_
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 "".
#define RCUTILS_WARN_UNUSED
Definition: macros.h:24
#define RCUTILS_PUBLIC
Definition: visibility_control.h:48