1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prenv.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,118 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef prenv_h___
1.10 +#define prenv_h___
1.11 +
1.12 +#include "prtypes.h"
1.13 +
1.14 +/*******************************************************************************/
1.15 +/*******************************************************************************/
1.16 +/****************** THESE FUNCTIONS MAY NOT BE THREAD SAFE *********************/
1.17 +/*******************************************************************************/
1.18 +/*******************************************************************************/
1.19 +
1.20 +PR_BEGIN_EXTERN_C
1.21 +
1.22 +/*
1.23 +** PR_GetEnv() -- Retrieve value of environment variable
1.24 +**
1.25 +** Description:
1.26 +** PR_GetEnv() is modeled on Unix getenv().
1.27 +**
1.28 +**
1.29 +** Inputs:
1.30 +** var -- The name of the environment variable
1.31 +**
1.32 +** Returns:
1.33 +** The value of the environment variable 'var' or NULL if
1.34 +** the variable is undefined.
1.35 +**
1.36 +** Restrictions:
1.37 +** You'd think that a POSIX getenv(), putenv() would be
1.38 +** consistently implemented everywhere. Surprise! It is not. On
1.39 +** some platforms, a putenv() where the argument is of
1.40 +** the form "name" causes the named environment variable to
1.41 +** be un-set; that is: a subsequent getenv() returns NULL. On
1.42 +** other platforms, the putenv() fails, on others, it is a
1.43 +** no-op. Similarly, a putenv() where the argument is of the
1.44 +** form "name=" causes the named environment variable to be
1.45 +** un-set; a subsequent call to getenv() returns NULL. On
1.46 +** other platforms, a subsequent call to getenv() returns a
1.47 +** pointer to a null-string (a byte of zero).
1.48 +**
1.49 +** PR_GetEnv(), PR_SetEnv() provide a consistent behavior
1.50 +** across all supported platforms. There are, however, some
1.51 +** restrictions and some practices you must use to achieve
1.52 +** consistent results everywhere.
1.53 +**
1.54 +** When manipulating the environment there is no way to un-set
1.55 +** an environment variable across all platforms. We suggest
1.56 +** you interpret the return of a pointer to null-string to
1.57 +** mean the same as a return of NULL from PR_GetEnv().
1.58 +**
1.59 +** A call to PR_SetEnv() where the parameter is of the form
1.60 +** "name" will return PR_FAILURE; the environment remains
1.61 +** unchanged. A call to PR_SetEnv() where the parameter is
1.62 +** of the form "name=" may un-set the envrionment variable on
1.63 +** some platforms; on others it may set the value of the
1.64 +** environment variable to the null-string.
1.65 +**
1.66 +** For example, to test for NULL return or return of the
1.67 +** null-string from PR_GetEnv(), use the following code
1.68 +** fragment:
1.69 +**
1.70 +** char *val = PR_GetEnv("foo");
1.71 +** if ((NULL == val) || ('\0' == *val)) {
1.72 +** ... interpret this as un-set ...
1.73 +** }
1.74 +**
1.75 +** The caller must ensure that the string passed
1.76 +** to PR_SetEnv() is persistent. That is: The string should
1.77 +** not be on the stack, where it can be overwritten
1.78 +** on return from the function calling PR_SetEnv().
1.79 +** Similarly, the string passed to PR_SetEnv() must not be
1.80 +** overwritten by other actions of the process. ... Some
1.81 +** platforms use the string by reference rather than copying
1.82 +** it into the environment space. ... You have been warned!
1.83 +**
1.84 +** Use of platform-native functions that manipulate the
1.85 +** environment (getenv(), putenv(),
1.86 +** SetEnvironmentVariable(), etc.) must not be used with
1.87 +** NSPR's similar functions. The platform-native functions
1.88 +** may not be thread safe and/or may operate on different
1.89 +** conceptual environment space than that operated upon by
1.90 +** NSPR's functions or other environment manipulating
1.91 +** functions on the same platform. (!)
1.92 +**
1.93 +*/
1.94 +NSPR_API(char*) PR_GetEnv(const char *var);
1.95 +
1.96 +/*
1.97 +** PR_SetEnv() -- set, unset or change an environment variable
1.98 +**
1.99 +** Description:
1.100 +** PR_SetEnv() is modeled on the Unix putenv() function.
1.101 +**
1.102 +** Inputs:
1.103 +** string -- pointer to a caller supplied
1.104 +** constant, persistent string of the form name=value. Where
1.105 +** name is the name of the environment variable to be set or
1.106 +** changed; value is the value assigned to the variable.
1.107 +**
1.108 +** Returns:
1.109 +** PRStatus.
1.110 +**
1.111 +** Restrictions:
1.112 +** See the Restrictions documented in the description of
1.113 +** PR_GetEnv() in this header file.
1.114 +**
1.115 +**
1.116 +*/
1.117 +NSPR_API(PRStatus) PR_SetEnv(const char *string);
1.118 +
1.119 +PR_END_EXTERN_C
1.120 +
1.121 +#endif /* prenv_h___ */
