Back to index

lightning-sunbird  0.9+nobinonly
prenv.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef prenv_h___
00039 #define prenv_h___
00040 
00041 #include "prtypes.h"
00042 
00043 /*******************************************************************************/
00044 /*******************************************************************************/
00045 /****************** THESE FUNCTIONS MAY NOT BE THREAD SAFE *********************/
00046 /*******************************************************************************/
00047 /*******************************************************************************/
00048 
00049 PR_BEGIN_EXTERN_C
00050 
00051 /*
00052 ** PR_GetEnv() -- Retrieve value of environment variable
00053 ** 
00054 ** Description:
00055 ** PR_GetEnv() is modeled on Unix getenv().
00056 ** 
00057 ** 
00058 ** Inputs: 
00059 **   var -- The name of the environment variable
00060 ** 
00061 ** Returns:
00062 **   The value of the environment variable 'var' or NULL if
00063 ** the variable is undefined.
00064 ** 
00065 ** Restrictions:
00066 **   You'd think that a POSIX getenv(), putenv() would be
00067 **   consistently implemented everywhere. Surprise! It is not. On
00068 **   some platforms, a putenv() where the argument is of
00069 **   the form "name"  causes the named environment variable to
00070 **   be un-set; that is: a subsequent getenv() returns NULL. On
00071 **   other platforms, the putenv() fails, on others, it is a
00072 **   no-op. Similarly, a putenv() where the argument is of the
00073 **   form "name=" causes the named environment variable to be
00074 **   un-set; a subsequent call to getenv() returns NULL. On
00075 **   other platforms, a subsequent call to getenv() returns a
00076 **   pointer to a null-string (a byte of zero).
00077 ** 
00078 **   PR_GetEnv(), PR_SetEnv() provide a consistent behavior 
00079 **   across all supported platforms. There are, however, some
00080 **   restrictions and some practices you must use to achieve
00081 **   consistent results everywhere.
00082 ** 
00083 **   When manipulating the environment there is no way to un-set
00084 **   an environment variable across all platforms. We suggest
00085 **   you interpret the return of a pointer to null-string to
00086 **   mean the same as a return of NULL from PR_GetEnv().
00087 ** 
00088 **   A call to PR_SetEnv() where the parameter is of the form
00089 **   "name" will return PR_FAILURE; the environment remains
00090 **   unchanged. A call to PR_SetEnv() where the parameter is
00091 **   of the form "name=" may un-set the envrionment variable on
00092 **   some platforms; on others it may set the value of the
00093 **   environment variable to the null-string.
00094 ** 
00095 **   For example, to test for NULL return or return of the
00096 **   null-string from PR_GetEnv(), use the following code
00097 **   fragment:
00098 ** 
00099 **      char *val = PR_GetEnv("foo");
00100 **      if ((NULL == val) || ('\0' == *val)) { 
00101 **          ... interpret this as un-set ... 
00102 **      }
00103 ** 
00104 **   The caller must ensure that the string passed
00105 **   to PR_SetEnv() is persistent. That is: The string should
00106 **   not be on the stack, where it can be overwritten
00107 **   on return from the function calling PR_SetEnv().
00108 **   Similarly, the string passed to PR_SetEnv() must not be
00109 **   overwritten by other actions of the process. ... Some
00110 **   platforms use the string by reference rather than copying
00111 **   it into the environment space. ... You have been warned!
00112 ** 
00113 **   Use of platform-native functions that manipulate the
00114 **   environment (getenv(), putenv(), 
00115 **   SetEnvironmentVariable(), etc.) must not be used with
00116 **   NSPR's similar functions. The platform-native functions
00117 **   may not be thread safe and/or may operate on different
00118 **   conceptual environment space than that operated upon by
00119 **   NSPR's functions or other environment manipulating
00120 **   functions on the same platform. (!)
00121 ** 
00122 */
00123 NSPR_API(char*) PR_GetEnv(const char *var);
00124 
00125 /*
00126 ** PR_SetEnv() -- set, unset or change an environment variable
00127 ** 
00128 ** Description:
00129 ** PR_SetEnv() is modeled on the Unix putenv() function.
00130 ** 
00131 ** Inputs: 
00132 **   string -- pointer to a caller supplied
00133 **   constant, persistent string of the form name=value. Where
00134 **   name is the name of the environment variable to be set or
00135 **   changed; value is the value assigned to the variable.
00136 **
00137 ** Returns: 
00138 **   PRStatus.
00139 ** 
00140 ** Restrictions: 
00141 **   See the Restrictions documented in the description of
00142 **   PR_GetEnv() in this header file.
00143 ** 
00144 ** 
00145 */
00146 NSPR_API(PRStatus) PR_SetEnv(const char *string);
00147 
00148 /*
00149 ** DEPRECATED.  Use PR_SetEnv() instead.
00150 */
00151 #ifdef XP_MAC
00152 NSPR_API(PRIntn) PR_PutEnv(const char *string);
00153 #endif
00154 
00155 PR_END_EXTERN_C
00156 
00157 #endif /* prenv_h___ */