Re: BZ#10153: Document putenv and setenv return values

[Andreas Jaeger <aj at suse dot com>]

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