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