![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to prenv.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Synchronet] / sbbs / include / mozilla / nspr|
Return to prenv.h CVS log | Up to [Synchronet] / sbbs / include / mozilla / nspr |
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.