BZ#10153: Document putenv and setenv return values

[Andreas Jaeger]

On 04/08/2012 06:13 PM, Carlos O'Donell wrote:
> On Sun, Apr 8, 2012 at 11:37 AM, Andreas Jaeger<aj@suse.com>  wrote:
>>
>> The return values of putenv and setenv where not mentioned at all,
>> fixed with the appended patch.
>>
>> Ok to commit?
>>
>> Andreas
>>
>> 2012-04-08  Andreas Jaeger<aj@suse.de>
>>
>>         [BZ #10153]
>>         * manual/startup.texi (Environment Access): Describe return value
>>         for putenv and setenv.
>>
>> diff --git a/manual/startup.texi b/manual/startup.texi
>> index 93dca30..4cd99e5 100644
>> --- a/manual/startup.texi
>> +++ b/manual/startup.texi
>> @@ -335,6 +335,9 @@ definition is added to the environment.  Otherwise, the @var{string} is
>>   interpreted as the name of an environment variable, and any definition
>>   for this variable in the environment is removed.
>>
>> +If the function is successful it returns @code{0}.  Otherwise the return
>> +value is nonzero and @code{errno} is set to indicate the error.
>> +
>>   The difference to the @code{setenv} function is that the exact string
>>   given as the parameter @var{string} is put into the environment.  If the
>>   user should change the string after the @code{putenv} call this will
>> @@ -364,6 +367,9 @@ the old entry is replaced by the new one.
>>
>>   Please note that you cannot remove an entry completely using this function.
>>
>> +If the function is successful it returns @code{0}.  Otherwise the return
>> +value is @code{-1} and @code{errno} is set.
>> +
>>   This function was originally part of the BSD library but is now part of
>>   the Unix standard.
>>   @end deftypefun
>
> POSIX additionally says that if setenv fails the environment shall be unchanged.
>
> OK, with that additional change as long as our implementation actually
> does that :-)


thanks, here's what I'm committing,
Andreas

diff --git a/manual/startup.texi b/manual/startup.texi
index 93dca30..ed75e7b 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -335,6 +335,9 @@ definition is added to the environment.  Otherwise, 
the @var{string} is
  interpreted as the name of an environment variable, and any definition
  for this variable in the environment is removed.

+If the function is successful it returns @code{0}.  Otherwise the return
+value is nonzero and @code{errno} is set to indicate the error.
+
  The difference to the @code{setenv} function is that the exact string
  given as the parameter @var{string} is put into the environment.  If the
  user should change the string after the @code{putenv} call this will
@@ -364,6 +367,10 @@ the old entry is replaced by the new one.

  Please note that you cannot remove an entry completely using this 
function.

+If the function is successful it returns @code{0}.  Otherwise the
+environment is unchanged and the return value is @code{-1} and
+@code{errno} is set.
+
  This function was originally part of the BSD library but is now part of
  the Unix standard.
  @end deftypefun

-- 
  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
   SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
    GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126