• file
• revisions
• annotate
• diff
• comparison
• raw

nsprpub/pr/include/prenv.h@4ab42b5ab56c (annotated)

nsprpub/pr/include/prenv.h

Wed, 31 Dec 2014 07:53:36 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Wed, 31 Dec 2014 07:53:36 +0100

branch

TOR_BUG_3246

changeset 5

4ab42b5ab56c

permissions

-rw-r--r--

Correct small whitespace inconsistency, lost while renaming variables.

michael@0	1	/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0	2	/* This Source Code Form is subject to the terms of the Mozilla Public
michael@0	3	* License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0	4	* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0	5
michael@0	6	#ifndef prenv_h___
michael@0	7	#define prenv_h___
michael@0	8
michael@0	9	#include "prtypes.h"
michael@0	10
michael@0	11	/*******************************************************************************/
michael@0	12	/*******************************************************************************/
michael@0	13	/****************** THESE FUNCTIONS MAY NOT BE THREAD SAFE *********************/
michael@0	14	/*******************************************************************************/
michael@0	15	/*******************************************************************************/
michael@0	16
michael@0	17	PR_BEGIN_EXTERN_C
michael@0	18
michael@0	19	/*
michael@0	20	** PR_GetEnv() -- Retrieve value of environment variable
michael@0	21	**
michael@0	22	** Description:
michael@0	23	** PR_GetEnv() is modeled on Unix getenv().
michael@0	24	**
michael@0	25	**
michael@0	26	** Inputs:
michael@0	27	** var -- The name of the environment variable
michael@0	28	**
michael@0	29	** Returns:
michael@0	30	** The value of the environment variable 'var' or NULL if
michael@0	31	** the variable is undefined.
michael@0	32	**
michael@0	33	** Restrictions:
michael@0	34	** You'd think that a POSIX getenv(), putenv() would be
michael@0	35	** consistently implemented everywhere. Surprise! It is not. On
michael@0	36	** some platforms, a putenv() where the argument is of
michael@0	37	** the form "name" causes the named environment variable to
michael@0	38	** be un-set; that is: a subsequent getenv() returns NULL. On
michael@0	39	** other platforms, the putenv() fails, on others, it is a
michael@0	40	** no-op. Similarly, a putenv() where the argument is of the
michael@0	41	** form "name=" causes the named environment variable to be
michael@0	42	** un-set; a subsequent call to getenv() returns NULL. On
michael@0	43	** other platforms, a subsequent call to getenv() returns a
michael@0	44	** pointer to a null-string (a byte of zero).
michael@0	45	**
michael@0	46	** PR_GetEnv(), PR_SetEnv() provide a consistent behavior
michael@0	47	** across all supported platforms. There are, however, some
michael@0	48	** restrictions and some practices you must use to achieve
michael@0	49	** consistent results everywhere.
michael@0	50	**
michael@0	51	** When manipulating the environment there is no way to un-set
michael@0	52	** an environment variable across all platforms. We suggest
michael@0	53	** you interpret the return of a pointer to null-string to
michael@0	54	** mean the same as a return of NULL from PR_GetEnv().
michael@0	55	**
michael@0	56	** A call to PR_SetEnv() where the parameter is of the form
michael@0	57	** "name" will return PR_FAILURE; the environment remains
michael@0	58	** unchanged. A call to PR_SetEnv() where the parameter is
michael@0	59	** of the form "name=" may un-set the envrionment variable on
michael@0	60	** some platforms; on others it may set the value of the
michael@0	61	** environment variable to the null-string.
michael@0	62	**
michael@0	63	** For example, to test for NULL return or return of the
michael@0	64	** null-string from PR_GetEnv(), use the following code
michael@0	65	** fragment:
michael@0	66	**
michael@0	67	** char *val = PR_GetEnv("foo");
michael@0	68	** if ((NULL == val) || ('\0' == *val)) {
michael@0	69	** ... interpret this as un-set ...
michael@0	70	** }
michael@0	71	**
michael@0	72	** The caller must ensure that the string passed
michael@0	73	** to PR_SetEnv() is persistent. That is: The string should
michael@0	74	** not be on the stack, where it can be overwritten
michael@0	75	** on return from the function calling PR_SetEnv().
michael@0	76	** Similarly, the string passed to PR_SetEnv() must not be
michael@0	77	** overwritten by other actions of the process. ... Some
michael@0	78	** platforms use the string by reference rather than copying
michael@0	79	** it into the environment space. ... You have been warned!
michael@0	80	**
michael@0	81	** Use of platform-native functions that manipulate the
michael@0	82	** environment (getenv(), putenv(),
michael@0	83	** SetEnvironmentVariable(), etc.) must not be used with
michael@0	84	** NSPR's similar functions. The platform-native functions
michael@0	85	** may not be thread safe and/or may operate on different
michael@0	86	** conceptual environment space than that operated upon by
michael@0	87	** NSPR's functions or other environment manipulating
michael@0	88	** functions on the same platform. (!)
michael@0	89	**
michael@0	90	*/
michael@0	91	NSPR_API(char*) PR_GetEnv(const char *var);
michael@0	92
michael@0	93	/*
michael@0	94	** PR_SetEnv() -- set, unset or change an environment variable
michael@0	95	**
michael@0	96	** Description:
michael@0	97	** PR_SetEnv() is modeled on the Unix putenv() function.
michael@0	98	**
michael@0	99	** Inputs:
michael@0	100	** string -- pointer to a caller supplied
michael@0	101	** constant, persistent string of the form name=value. Where
michael@0	102	** name is the name of the environment variable to be set or
michael@0	103	** changed; value is the value assigned to the variable.
michael@0	104	**
michael@0	105	** Returns:
michael@0	106	** PRStatus.
michael@0	107	**
michael@0	108	** Restrictions:
michael@0	109	** See the Restrictions documented in the description of
michael@0	110	** PR_GetEnv() in this header file.
michael@0	111	**
michael@0	112	**
michael@0	113	*/
michael@0	114	NSPR_API(PRStatus) PR_SetEnv(const char *string);
michael@0	115
michael@0	116	PR_END_EXTERN_C
michael@0	117
michael@0	118	#endif /* prenv_h___ */