root/opal/util/opal_environ.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


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

/* [<][>][^][v][top][bottom][index][help] */