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