1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
/*
* Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
* University Research and Technology
* Corporation. All rights reserved.
* Copyright (c) 2004-2005 The University of Tennessee and The University
* of Tennessee Research Foundation. All rights
* reserved.
* Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
* University of Stuttgart. All rights reserved.
* Copyright (c) 2004-2005 The Regents of the University of California.
* All rights reserved.
* Copyright (c) 2007-2013 Los Alamos National Security, LLC. All rights
* reserved.
* $COPYRIGHT$
*
* Additional copyrights may follow
*
* $HEADER$
*/
/**
* @file
*
* Generic helper routines for environment manipulation.
*/
#ifndef OPAL_ENVIRON_H
#define OPAL_ENVIRON_H
#include "opal_config.h"
#ifdef HAVE_CRT_EXTERNS_H
# include <crt_externs.h>
#endif
BEGIN_C_DECLS
/**
* Merge two environ-like arrays into a single, new array, ensuring
* that there are no duplicate entries.
*
* @param minor Set 1 of the environ's to merge
* @param major Set 2 of the environ's to merge
* @retval New array of environ
*
* Merge two environ-like arrays into a single, new array,
* ensuring that there are no duplicate entries. If there are
* duplicates, entries in the \em major array are favored over
* those in the \em minor array.
*
* Both \em major and \em 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 \em major and \em 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.
*/
OPAL_DECLSPEC char **opal_environ_merge(char **minor,
char **major) __opal_attribute_warn_unused_result__;
/**
* Portable version of setenv(3), allowing editing of any
* environ-like array.
*
* @param name String name of the environment variable to look for
* @param value String value to set (may be NULL)
* @param overwrite Whether to overwrite any existing value with
* the same name
* @param env The environment to use
*
* @retval OPAL_ERR_OUT_OF_RESOURCE If internal malloc() fails.
* @retval OPAL_EXISTS If the name already exists in \em env and
* \em overwrite is false (and therefore the \em value was not
* saved in \em env)
* @retval OPAL_SUCESS If the value replaced another value or is
* appended to \em env.
*
* \em env is expected to be a NULL-terminated array of pointers
* (argv-style). Note that unlike some implementations of
* putenv(3), if \em value is inserted in \em env, it is copied.
* So the caller can modify/free both \em name and \em value after
* opal_setenv() returns.
*
* The \em env array will be grown if necessary.
*
* It is permissible to invoke this function with the
* system-defined \em environ variable. For example:
*
* \code
* #include "opal/util/opal_environ.h"
* opal_setenv("foo", "bar", true, &environ);
* \endcode
*
* 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 permissible to call this function with an empty \em
* env, as long as it is pre-initialized with NULL:
*
* \code
* char **my_env = NULL;
* opal_setenv("foo", "bar", true, &my_env);
* \endcode
*/
OPAL_DECLSPEC int opal_setenv(const char *name, const char *value, bool overwrite, char ***env)
__opal_attribute_nonnull__(1);
/**
* Portable version of unsetenv(3), allowing editing of any
* environ-like array.
*
* @param name String name of the environment variable to look for
* @param env The environment to use
*
* @retval OPAL_ERR_OUT_OF_RESOURCE If an internal malloc fails.
* @retval OPAL_ERR_NOT_FOUND If \em name is not found in \em env.
* @retval OPAL_SUCCESS If \em name is found and successfully deleted.
*
* If \em name is found in \em env, the string corresponding to
* that entry is freed and its entry is eliminated from the array.
*/
OPAL_DECLSPEC int opal_unsetenv(const char *name, char ***env) __opal_attribute_nonnull__(1);
/* A consistent way to retrieve the home and tmp directory on all supported
* platforms.
*/
OPAL_DECLSPEC const char *opal_home_directory(void);
OPAL_DECLSPEC const char *opal_tmp_directory(void);
/* Some care is needed with environ on OS X when dealing with shared
libraries. Handle that care here... */
#ifdef HAVE__NSGETENVIRON
# define environ (*_NSGetEnviron())
#else
OPAL_DECLSPEC extern char **environ;
#endif
END_C_DECLS
#endif /* OPAL_ENVIRON */
|
