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 */