OpenMPI  0.1.1
opal_environ.h
Go to the documentation of this file.
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 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 #if !defined(__WINDOWS__)
137 
138 #ifdef HAVE__NSGETENVIRON
139 #define environ (*_NSGetEnviron())
140 #else
141 OPAL_DECLSPEC extern char **environ;
142 #endif
143 
144 #endif /* !defined(__WINDOWS__) */
145 
146 END_C_DECLS
147 
148 #endif /* OPAL_ENVIRON */
OPAL_DECLSPEC int opal_unsetenv(const char *name, char ***env) __opal_attribute_nonnull__(1)
Portable version of unsetenv(3), allowing editing of any environ-like array.
Definition: opal_environ.c:180
BEGIN_C_DECLS OPAL_DECLSPEC char ** opal_environ_merge(char **minor, char **major) __opal_attribute_warn_unused_result__
Merge two environ-like arrays into a single, new array, ensuring that there are no duplicate entries...
Definition: opal_environ.c:43
OPAL_DECLSPEC int opal_setenv(const char *name, const char *value, bool overwrite, char ***env) __opal_attribute_nonnull__(1)
Portable version of setenv(3), allowing editing of any environ-like array.
Definition: opal_environ.c:97