kmp_environment.cpp | Explore in Territory

/*
 * kmp_environment.cpp -- Handle environment variables OS-independently.
 */

//===----------------------------------------------------------------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

/* We use GetEnvironmentVariable for Windows* OS instead of getenv because the
   act of loading a DLL on Windows* OS makes any user-set environment variables
   (i.e. with putenv()) unavailable.  getenv() apparently gets a clean copy of
   the env variables as they existed at the start of the run. JH 12/23/2002

   On Windows* OS, there are two environments (at least, see below):

   1. Environment maintained by Windows* OS on IA-32 architecture. Accessible
      through GetEnvironmentVariable(), SetEnvironmentVariable(), and
      GetEnvironmentStrings().

   2. Environment maintained by C RTL. Accessible through getenv(), putenv().

   putenv() function updates both C and Windows* OS on IA-32 architecture.
   getenv() function search for variables in C RTL environment only.
   Windows* OS on IA-32 architecture functions work *only* with Windows* OS on
   IA-32 architecture.

   Windows* OS on IA-32 architecture maintained by OS, so there is always only
   one Windows* OS on IA-32 architecture per process. Changes in Windows* OS on
   IA-32 architecture are process-visible.

   C environment maintained by C RTL. Multiple copies of C RTL may be present
   in the process, and each C RTL maintains its own environment. :-(

   Thus, proper way to work with environment on Windows* OS is:

   1. Set variables with putenv() function -- both C and Windows* OS on IA-32
      architecture are being updated. Windows* OS on IA-32 architecture may be
      considered primary target, while updating C RTL environment is free bonus.

   2. Get variables with GetEnvironmentVariable() -- getenv() does not
      search Windows* OS on IA-32 architecture, and can not see variables
      set with SetEnvironmentVariable().

   2007-04-05 -- lev
*/

#include "kmp_environment.h"

#include "kmp.h" //
#include "kmp_i18n.h"
#include "kmp_os.h" // KMP_OS_*.
#include "kmp_str.h" // __kmp_str_*().

#if KMP_OS_UNIX
#include <stdlib.h> // getenv, setenv, unsetenv.
#include <string.h> // strlen, strcpy.
#if KMP_OS_DARWIN
#include <crt_externs.h>
#define environ …
#else
extern char **environ;
#endif
#elif KMP_OS_WINDOWS
#include <windows.h> // GetEnvironmentVariable, SetEnvironmentVariable,
// GetLastError.
#else
#error Unknown or unsupported OS.
#endif

// TODO: Eliminate direct memory allocations, use string operations instead.

static inline void *allocate(size_t size) { … } // allocate

char *__kmp_env_get(char const *name) { … } // func __kmp_env_get

// TODO: Find and replace all regular free() with __kmp_env_free().

void __kmp_env_free(char const **value) { … } // func __kmp_env_free

int __kmp_env_exists(char const *name) { … } // func __kmp_env_exists

void __kmp_env_set(char const *name, char const *value, int overwrite) { … } // func __kmp_env_set

void __kmp_env_unset(char const *name) { … } // func __kmp_env_unset

/* Intel OpenMP RTL string representation of environment: just a string of
   characters, variables are separated with vertical bars, e. g.:

        "KMP_WARNINGS=0|KMP_AFFINITY=compact|"

    Empty variables are allowed and ignored:

        "||KMP_WARNINGS=1||"
*/

static void
___kmp_env_blk_parse_string(kmp_env_blk_t *block, // M: Env block to fill.
                            char const *env // I: String to parse.
) { … }

/* Windows* OS (actually, DOS) environment block is a piece of memory with
   environment variables. Each variable is terminated with zero byte, entire
   block is terminated with one extra zero byte, so we have two zero bytes at
   the end of environment block, e. g.:

        "HOME=C:\\users\\lev\x00OS=Windows_NT\x00\x00"

    It is not clear how empty environment is represented. "\x00\x00"?
*/

#if KMP_OS_WINDOWS
static void ___kmp_env_blk_parse_windows(
    kmp_env_blk_t *block, // M: Env block to fill.
    char const *env // I: Pointer to Windows* OS (DOS) environment block.
) {

  char *bulk = NULL;
  kmp_env_var_t *vars = NULL;
  int count = 0; // Number of used elements in vars array.
  int size = 0; // Size of bulk.

  char *name; // Pointer to name of variable.
  char *value; // Pointer to value.

  if (env != NULL) {

    // Loop thru all the vars in environment block. Count variables, find size
    // of block.
    {
      char const *var; // Pointer to beginning of var.
      int len; // Length of variable.
      count = 0;
      var =
          env; // The first variable starts and beginning of environment block.
      len = KMP_STRLEN(var);
      while (len != 0) {
        ++count;
        size = size + len + 1;
        var = var + len +
              1; // Move pointer to the beginning of the next variable.
        len = KMP_STRLEN(var);
      }
      size =
          size + 1; // Total size of env block, including terminating zero byte.
    }

    // Copy original block to bulk, we will modify bulk, not original block.
    bulk = (char *)allocate(size);
    KMP_MEMCPY_S(bulk, size, env, size);
    // Allocate vars array.
    vars = (kmp_env_var_t *)allocate(count * sizeof(kmp_env_var_t));

    // Loop thru all the vars, now in bulk.
    {
      char *var; // Pointer to beginning of var.
      int len; // Length of variable.
      count = 0;
      var = bulk;
      len = KMP_STRLEN(var);
      while (len != 0) {
        // Save variable in vars array.
        __kmp_str_split(var, '=', &name, &value);
        vars[count].name = name;
        vars[count].value = value;
        ++count;
        // Get the next var.
        var = var + len + 1;
        len = KMP_STRLEN(var);
      }
    }
  }

  // Fill out result.
  block->bulk = bulk;
  block->vars = vars;
  block->count = count;
}
#endif

/* Unix environment block is a array of pointers to variables, last pointer in
   array is NULL:

        { "HOME=/home/lev", "TERM=xterm", NULL }
*/

#if KMP_OS_UNIX
static void
___kmp_env_blk_parse_unix(kmp_env_blk_t *block, // M: Env block to fill.
                          char **env // I: Unix environment to parse.
) { … }
#endif

void __kmp_env_blk_init(kmp_env_blk_t *block, // M: Block to initialize.
                        char const *bulk // I: Initialization string, or NULL.
) { … } // __kmp_env_blk_init

static int ___kmp_env_var_cmp( // Comparison function for qsort().
    kmp_env_var_t const *lhs, kmp_env_var_t const *rhs) { … }

void __kmp_env_blk_sort(
    kmp_env_blk_t *block // M: Block of environment variables to sort.
) { … } // __kmp_env_block_sort

void __kmp_env_blk_free(
    kmp_env_blk_t *block // M: Block of environment variables to free.
) { … } // __kmp_env_blk_free

char const * // R: Value of variable or NULL if variable does not exist.
__kmp_env_blk_var(kmp_env_blk_t *block, // I: Block of environment variables.
                  char const *name // I: Name of variable to find.
) { … } // __kmp_env_block_var

// end of file //
llvm/openmp/runtime/src/kmp_environment.cpp
