Return to prenv.h CVS log

Up to [Synchronet] / sbbs / include / mozilla / nspr

Annotation of sbbs/include/mozilla/nspr/prenv.h, revision 1.1

1.1     ! root        1: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
        !             2: /* 
        !             3:  * The contents of this file are subject to the Mozilla Public
        !             4:  * License Version 1.1 (the "License"); you may not use this file
        !             5:  * except in compliance with the License. You may obtain a copy of
        !             6:  * the License at http://www.mozilla.org/MPL/
        !             7:  * 
        !             8:  * Software distributed under the License is distributed on an "AS
        !             9:  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
        !            10:  * implied. See the License for the specific language governing
        !            11:  * rights and limitations under the License.
        !            12:  * 
        !            13:  * The Original Code is the Netscape Portable Runtime (NSPR).
        !            14:  * 
        !            15:  * The Initial Developer of the Original Code is Netscape
        !            16:  * Communications Corporation.  Portions created by Netscape are 
        !            17:  * Copyright (C) 1998-2000 Netscape Communications Corporation.  All
        !            18:  * Rights Reserved.
        !            19:  * 
        !            20:  * Contributor(s):
        !            21:  * 
        !            22:  * Alternatively, the contents of this file may be used under the
        !            23:  * terms of the GNU General Public License Version 2 or later (the
        !            24:  * "GPL"), in which case the provisions of the GPL are applicable 
        !            25:  * instead of those above.  If you wish to allow use of your 
        !            26:  * version of this file only under the terms of the GPL and not to
        !            27:  * allow others to use your version of this file under the MPL,
        !            28:  * indicate your decision by deleting the provisions above and
        !            29:  * replace them with the notice and other provisions requiored by
        !            30:  * the GPL.  If you do not delete the provisions above, a recipient
        !            31:  * may use your version of this file under either the MPL or the
        !            32:  * GPL.
        !            33:  */
        !            34: 
        !            35: #ifndef prenv_h___
        !            36: #define prenv_h___
        !            37: 
        !            38: #include "prtypes.h"
        !            39: 
        !            40: /*******************************************************************************/
        !            41: /*******************************************************************************/
        !            42: /****************** THESE FUNCTIONS MAY NOT BE THREAD SAFE *********************/
        !            43: /*******************************************************************************/
        !            44: /*******************************************************************************/
        !            45: 
        !            46: PR_BEGIN_EXTERN_C
        !            47: 
        !            48: /*
        !            49: ** PR_GetEnv() -- Retrieve value of environment variable
        !            50: ** 
        !            51: ** Description:
        !            52: ** PR_GetEnv() is modeled on Unix getenv().
        !            53: ** 
        !            54: ** 
        !            55: ** Inputs: 
        !            56: **   var -- The name of the environment variable
        !            57: ** 
        !            58: ** Returns:
        !            59: **   The value of the environment variable 'var' or NULL if
        !            60: ** the variable is undefined.
        !            61: ** 
        !            62: ** Restrictions:
        !            63: **   You'd think that a POSIX getenv(), putenv() would be
        !            64: **   consistently implemented everywhere. Surprise! It is not. On
        !            65: **   some platforms, a putenv() where the argument is of
        !            66: **   the form "name"  causes the named environment variable to
        !            67: **   be un-set; that is: a subsequent getenv() returns NULL. On
        !            68: **   other platforms, the putenv() fails, on others, it is a
        !            69: **   no-op. Similarly, a putenv() where the argument is of the
        !            70: **   form "name=" causes the named environment variable to be
        !            71: **   un-set; a subsequent call to getenv() returns NULL. On
        !            72: **   other platforms, a subsequent call to getenv() returns a
        !            73: **   pointer to a null-string (a byte of zero).
        !            74: ** 
        !            75: **   PR_GetEnv(), PR_SetEnv() provide a consistent behavior 
        !            76: **   across all supported platforms. There are, however, some
        !            77: **   restrictions and some practices you must use to achieve
        !            78: **   consistent results everywhere.
        !            79: ** 
        !            80: **   When manipulating the environment there is no way to un-set
        !            81: **   an environment variable across all platforms. We suggest
        !            82: **   you interpret the return of a pointer to null-string to
        !            83: **   mean the same as a return of NULL from PR_GetEnv().
        !            84: ** 
        !            85: **   A call to PR_SetEnv() where the parameter is of the form
        !            86: **   "name" will return PR_FAILURE; the environment remains
        !            87: **   unchanged. A call to PR_SetEnv() where the parameter is
        !            88: **   of the form "name=" may un-set the envrionment variable on
        !            89: **   some platforms; on others it may set the value of the
        !            90: **   environment variable to the null-string.
        !            91: ** 
        !            92: **   For example, to test for NULL return or return of the
        !            93: **   null-string from PR_GetEnv(), use the following code
        !            94: **   fragment:
        !            95: ** 
        !            96: **      char *val = PR_GetEnv("foo");
        !            97: **      if ((NULL == val) || ('\0' == *val)) { 
        !            98: **          ... interpret this as un-set ... 
        !            99: **      }
        !           100: ** 
        !           101: **   The caller must ensure that the string passed
        !           102: **   to PR_SetEnv() is persistent. That is: The string should
        !           103: **   not be on the stack, where it can be overwritten
        !           104: **   on return from the function calling PR_SetEnv().
        !           105: **   Similarly, the string passed to PR_SetEnv() must not be
        !           106: **   overwritten by other actions of the process. ... Some
        !           107: **   platforms use the string by reference rather than copying
        !           108: **   it into the environment space. ... You have been warned!
        !           109: ** 
        !           110: **   Use of platform-native functions that manipulate the
        !           111: **   environment (getenv(), putenv(), 
        !           112: **   SetEnvironmentVariable(), etc.) must not be used with
        !           113: **   NSPR's similar functions. The platform-native functions
        !           114: **   may not be thread safe and/or may operate on different
        !           115: **   conceptual environment space than that operated upon by
        !           116: **   NSPR's functions or other environment manipulating
        !           117: **   functions on the same platform. (!)
        !           118: ** 
        !           119: */
        !           120: NSPR_API(char*) PR_GetEnv(const char *var);
        !           121: 
        !           122: /*
        !           123: ** PR_SetEnv() -- set, unset or change an environment variable
        !           124: ** 
        !           125: ** Description:
        !           126: ** PR_SetEnv() is modeled on the Unix putenv() function.
        !           127: ** 
        !           128: ** Inputs: 
        !           129: **   string -- pointer to a caller supplied
        !           130: **   constant, persistent string of the form name=value. Where
        !           131: **   name is the name of the environment variable to be set or
        !           132: **   changed; value is the value assigned to the variable.
        !           133: **
        !           134: ** Returns: 
        !           135: **   PRStatus.
        !           136: ** 
        !           137: ** Restrictions: 
        !           138: **   See the Restrictions documented in the description of
        !           139: **   PR_GetEnv() in this header file.
        !           140: ** 
        !           141: ** 
        !           142: */
        !           143: NSPR_API(PRStatus) PR_SetEnv(const char *string);
        !           144: 
        !           145: /*
        !           146: ** DEPRECATED.  Use PR_SetEnv() instead.
        !           147: */
        !           148: #ifdef XP_MAC
        !           149: NSPR_API(PRIntn) PR_PutEnv(const char *string);
        !           150: #endif
        !           151: 
        !           152: PR_END_EXTERN_C
        !           153: 
        !           154: #endif /* prenv_h___ */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.