Re: doc: Mention gnulib putenv module?
On 5/17/24 2:38 AM, Bruno Haible wrote: > Now we can use the usual doc structure. > > > 2024-05-17 Bruno Haible > > putenv-gnu: Update documentation. > * doc/posix-functions/putenv.texi: Refer also to the glibc > documentation. Use the usual doc structure. Looks good. Thanks! Collin
Re: doc: Mention gnulib putenv module?
Collin Funk wrote:
> Done in the two attached patches.
Now we can use the usual doc structure.
2024-05-17 Bruno Haible
putenv-gnu: Update documentation.
* doc/posix-functions/putenv.texi: Refer also to the glibc
documentation. Use the usual doc structure.
diff --git a/doc/posix-functions/putenv.texi b/doc/posix-functions/putenv.texi
index ff06ea5062..87fc2f295c 100644
--- a/doc/posix-functions/putenv.texi
+++ b/doc/posix-functions/putenv.texi
@@ -2,18 +2,32 @@
@section @code{putenv}
@findex putenv
-POSIX specification:@*
@url{https://pubs.opengroup.org/onlinepubs/9699919799/functions/putenv.html}
+POSIX specification:@*
@url{https://pubs.opengroup.org/onlinepubs/9699919799/functions/putenv.html},
+amended through @url{https://www.austingroupbugs.net/view.php?id=1598}.
+
+Documentation:@*
+@ifinfo
+@ref{Environment Access,,Environment Access,libc}.
+@end ifinfo
+@ifnotinfo
+@url{https://www.gnu.org/software/libc/manual/html_node/Environment-Access.html}.
+@end ifnotinfo
+
+Note: POSIX @code{putenv} supports
+adding or changing the value of an environment variable,
+while glibc also supports removing an environment variable
+(as if by @code{unsetenv}).
Gnulib module: putenv-gnu
Portability problems fixed by Gnulib:
@itemize
+@item
+This function does not support removing an environment variable
+on some platforms:
+macOS 12.5, FreeBSD 14.0, NetBSD 10.0, OpenBSD 7.5, AIX 7.3.1, HP-UX 11.31,
Solaris 11.4, mingw, MSVC 14, Android 11.0.
@end itemize
Portability problems not fixed by Gnulib:
@itemize
@end itemize
-
-Extension: Gnulib provides a module @samp{putenv-gnu} that substitutes a
-@code{putenv} implementation that can also be used to remove environment
-variables.
Re: doc: Mention gnulib putenv module?
> Done in the two attached patches. I ran the following in Coreutils: > > ./bootstrap --no-git --skip-po --gnulib-srcdir="$GNULIB_SRCDIR" > > and everything worked fine. Thanks a lot! Bruno
Re: doc: Mention gnulib putenv module?
Hi Bruno,
On 5/16/24 1:54 PM, Bruno Haible wrote:
>> Thanks for the guide.
>
> And also update doc/posix-functions/putenv.texi.
>
>> Should I update occurrences of 'putenv' to
>> 'putenv-gnu' in dependencies
>
> Yes. (But this can come in a second commit.)
>
>> and then mark 'putenv' with the
>> 'obsolete' status? That way './bootstrap' will print a small warning
>> letting people know to change it eventually.
>
> Mark it as "deprecated", not "obsolete", please. See [1].
Done in the two attached patches. I ran the following in Coreutils:
./bootstrap --no-git --skip-po --gnulib-srcdir="$GNULIB_SRCDIR"
and everything worked fine. Notice and correct import, so hopefully no
breakage should occur. :)
CollinFrom 5d2987e6ca5a7d06b4135ab17314051d363621f2 Mon Sep 17 00:00:00 2001
From: Collin Funk
Date: Thu, 16 May 2024 15:56:47 -0700
Subject: [PATCH 1/2] Rename module 'putenv' to 'putenv-gnu'.
* modules/putenv-gnu: Renamed from modules/putenv.
(Description): Mention the removal of environment variables.
* modules/putenv-gnu-tests: Renamed from modules/putenv-tests.
* modules/putenv: New file, an indirection to the new module.
* doc/posix-functions/putenv.texi: Mention the new module name.
* NEWS: Mention the change.
---
ChangeLog | 10 +++
NEWS | 2 ++
doc/posix-functions/putenv.texi| 4 +--
modules/putenv | 24 +--
modules/putenv-gnu | 34 ++
modules/{putenv-tests => putenv-gnu-tests} | 0
6 files changed, 56 insertions(+), 18 deletions(-)
create mode 100644 modules/putenv-gnu
rename modules/{putenv-tests => putenv-gnu-tests} (100%)
diff --git a/ChangeLog b/ChangeLog
index 8bccdfd2e1..f2bfa4246d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2024-05-16 Collin Funk
+
+ Rename module 'putenv' to 'putenv-gnu'.
+ * modules/putenv-gnu: Renamed from modules/putenv.
+ (Description): Mention the removal of environment variables.
+ * modules/putenv-gnu-tests: Renamed from modules/putenv-tests.
+ * modules/putenv: New file, an indirection to the new module.
+ * doc/posix-functions/putenv.texi: Mention the new module name.
+ * NEWS: Mention the change.
+
2024-05-16 Collin Funk
putenv: Add tests.
diff --git a/NEWS b/NEWS
index 6caf3ad8e1..57540c8375 100644
--- a/NEWS
+++ b/NEWS
@@ -74,6 +74,8 @@ User visible incompatible changes
DateModules Changes
+2024-05-16 putenv This module is renamed to 'putenv-gnu'.
+
2024-02-21 *printf-posix These modules no longer support the 'n' directive
by default. In order to keep the 'n' directive
enabled, you need to additionally request the
diff --git a/doc/posix-functions/putenv.texi b/doc/posix-functions/putenv.texi
index b0ca4ab8b5..ff06ea5062 100644
--- a/doc/posix-functions/putenv.texi
+++ b/doc/posix-functions/putenv.texi
@@ -4,7 +4,7 @@ @node putenv
POSIX specification:@* @url{https://pubs.opengroup.org/onlinepubs/9699919799/functions/putenv.html}
-Gnulib module: ---
+Gnulib module: putenv-gnu
Portability problems fixed by Gnulib:
@itemize
@@ -14,6 +14,6 @@ @node putenv
@itemize
@end itemize
-Extension: Gnulib provides a module @samp{putenv} that substitutes a
+Extension: Gnulib provides a module @samp{putenv-gnu} that substitutes a
@code{putenv} implementation that can also be used to remove environment
variables.
diff --git a/modules/putenv b/modules/putenv
index a5a7c8d795..acc0659d8b 100644
--- a/modules/putenv
+++ b/modules/putenv
@@ -1,28 +1,20 @@
Description:
putenv() function: change or add an environment variable.
+Status:
+deprecated
+
+Notice:
+This module is deprecated. Use the module 'putenv-gnu' instead.
+
Files:
-lib/putenv.c
-m4/putenv.m4
Depends-on:
-stdlib
-environ [test $REPLACE_PUTENV = 1]
-free-posix [test $REPLACE_PUTENV = 1]
-malloc-posix[test $REPLACE_PUTENV = 1]
+putenv-gnu
configure.ac:
-gl_FUNC_PUTENV
-gl_CONDITIONAL([GL_COND_OBJ_PUTENV], [test $REPLACE_PUTENV = 1])
-AM_COND_IF([GL_COND_OBJ_PUTENV], [
- gl_PREREQ_PUTENV
-])
-gl_STDLIB_MODULE_INDICATOR([putenv])
Makefile.am:
-if GL_COND_OBJ_PUTENV
-lib_SOURCES += putenv.c
-endif
Include:
@@ -31,4 +23,4 @@ License:
LGPL
Maintainer:
-Jim Meyering, glibc
+all
diff --git a/modules/putenv-gnu b/modules/putenv-gnu
new file mode 100644
index 00..be929f60be
--- /dev/null
+++ b/modules/putenv-gnu
@@ -0,0 +1,34 @@
+Description:
+putenv() function: change, add, or remove an environment variable.
+
+Files:
+lib/putenv.c
+m4/putenv.m4
+
+Depends-on:
+stdlib
+environ [test $REPLACE_PUTENV = 1]
+free-posix [test $REPLACE_PUTENV = 1]
+malloc-posix[test $REPLACE_PUTENV = 1]
+
+configure.ac:
+gl_FUNC_PUTENV
+gl_CONDITIONAL([GL_COND_OBJ_PUTENV], [test $REPLACE_PUTENV = 1])
+AM_COND_IF([GL_COND_OBJ_PUTENV], [
+ gl_PREREQ_PUTENV
+])
Re: doc: Mention gnulib putenv module?
Hi Collin, > On 5/16/24 5:45 AM, Bruno Haible wrote: > > The way to deal with it, that is most consistent with the rest of Gnulib, > > is as follows: > > > > - Rename the 'putenv' module to 'putenv-gnu'. > > > > - Also change its description from: > > putenv() function: change or add an environment variable. > > to: > > putenv() function: change, add, or remove an environment variable. > > > > - Rename the 'putenv-tests' module to 'putenv-gnu-tests'. > > > > - Add a new 'putenv' module that is merely an indirection to 'putenv-gnu' > > (for backward compatibility, in order not to break coreutils, gcal, > > guile, > > octave, etc.). In the NEWS file mention > >2024-MM-DD putenv This module is renamed to 'putenv-gnu'. > > Thanks for the guide. And also update doc/posix-functions/putenv.texi. > Should I update occurrences of 'putenv' to > 'putenv-gnu' in dependencies Yes. (But this can come in a second commit.) > and then mark 'putenv' with the > 'obsolete' status? That way './bootstrap' will print a small warning > letting people know to change it eventually. Mark it as "deprecated", not "obsolete", please. See [1]. Bruno [1] https://lists.gnu.org/archive/html/bug-gnulib/2024-05/msg00080.html
Re: doc: Mention gnulib putenv module?
Hi Bruno, On 5/16/24 5:45 AM, Bruno Haible wrote: > The way to deal with it, that is most consistent with the rest of Gnulib, > is as follows: > > - Rename the 'putenv' module to 'putenv-gnu'. > > - Also change its description from: > putenv() function: change or add an environment variable. > to: > putenv() function: change, add, or remove an environment variable. > > - Rename the 'putenv-tests' module to 'putenv-gnu-tests'. > > - Add a new 'putenv' module that is merely an indirection to 'putenv-gnu' > (for backward compatibility, in order not to break coreutils, gcal, guile, > octave, etc.). In the NEWS file mention >2024-MM-DD putenv This module is renamed to 'putenv-gnu'. Thanks for the guide. Should I update occurrences of 'putenv' to 'putenv-gnu' in dependencies and then mark 'putenv' with the 'obsolete' status? That way './bootstrap' will print a small warning letting people know to change it eventually. Collin
Re: doc: Mention gnulib putenv module?
Hi Collin, > > But maybe something could be clarified: > > - Does POSIX still not allow to remove an environment variable using > > this function? > > I don't think that POSIX Issue 7 disallows it [1]. It appears that the > behavior when '=' is not in the string is up for the implementation > decide. This was reported in 2022 and the next revision will clarify > that the environment variable can be removed or the function can fail > with errno == EINVAL and a non-zero return value [2]. > > > > - On which platforms does the native putenv() not allow to remove an > > environment variable using this function? > > Good question. The POSIX report is well written so I won't retype it > here [2]. :) OK, I see. The way to deal with it, that is most consistent with the rest of Gnulib, is as follows: - Rename the 'putenv' module to 'putenv-gnu'. - Also change its description from: putenv() function: change or add an environment variable. to: putenv() function: change, add, or remove an environment variable. - Rename the 'putenv-tests' module to 'putenv-gnu-tests'. - Add a new 'putenv' module that is merely an indirection to 'putenv-gnu' (for backward compatibility, in order not to break coreutils, gcal, guile, octave, etc.). In the NEWS file mention 2024-MM-DD putenv This module is renamed to 'putenv-gnu'. Bruno
Re: doc: Mention gnulib putenv module?
Hi Bruno, On 5/16/24 3:19 AM, Bruno Haible wrote: >> Is there a reason why the Gnulib putenv module isn't mentioned on this >> line or can I apply this diff with a ChangeLog entry? > > It is mentioned at the end of this file. I saw. I was thinking maybe it should be mentioned on that line though. Similar to how execinfo was missing until a few days ago. > But maybe something could be clarified: > - Does POSIX still not allow to remove an environment variable using > this function? I don't think that POSIX Issue 7 disallows it [1]. It appears that the behavior when '=' is not in the string is up for the implementation decide. This was reported in 2022 and the next revision will clarify that the environment variable can be removed or the function can fail with errno == EINVAL and a non-zero return value [2]. > - On which platforms does the native putenv() not allow to remove an > environment variable using this function? Good question. The POSIX report is well written so I won't retype it here [2]. :) > I think this is related to very very old shells not having an 'unset' > primitive. Interesting. POSIX says that setenv() is preferred anyways. Collin [1] https://pubs.opengroup.org/onlinepubs/9699919799/functions/putenv.html [2] https://www.austingroupbugs.net/view.php?id=1598
Re: doc: Mention gnulib putenv module?
Hi Collin, > Is there a reason why the Gnulib putenv module isn't mentioned on this > line or can I apply this diff with a ChangeLog entry? It is mentioned at the end of this file. But maybe something could be clarified: - Does POSIX still not allow to remove an environment variable using this function? - On which platforms does the native putenv() not allow to remove an environment variable using this function? I think this is related to very very old shells not having an 'unset' primitive. Bruno
doc: Mention gnulib putenv module?
Is there a reason why the Gnulib putenv module isn't mentioned on this
line or can I apply this diff with a ChangeLog entry?
diff --git a/doc/posix-functions/putenv.texi b/doc/posix-functions/putenv.texi
index b0ca4ab8b5..d9e15f5e38 100644
--- a/doc/posix-functions/putenv.texi
+++ b/doc/posix-functions/putenv.texi
@@ -4,7 +4,7 @@ @node putenv
POSIX specification:@*
@url{https://pubs.opengroup.org/onlinepubs/9699919799/functions/putenv.html}
-Gnulib module: ---
+Gnulib module: putenv
Portability problems fixed by Gnulib:
@itemize
Collin
