--- a/ChangeLog	Mon Sep 03 21:19:16 2018 +0200
+++ b/ChangeLog	Thu May 31 08:52:40 2018 -0500
@@ -1,3 +1,9 @@
+2018-09-05  Eric Blake  <eblake@redhat.com>
+
+	doc: mention environ pitfall
+	* doc/posix-functions/environ.texi (environ): Assigning NULL to
+	environ is a glibc extension.
+
 2018-09-03  Bruno Haible  <bruno@clisp.org>
 
 	gnulib-tool: Fix build order when $testsbase is a subdir of $sourcebase.

--- a/doc/posix-functions/environ.texi	Mon Sep 03 21:19:16 2018 +0200
+++ b/doc/posix-functions/environ.texi	Thu May 31 08:52:40 2018 -0500
@@ -34,4 +34,11 @@
 @item
 The address of this variable is not a compile-time constant on some platforms:
 mingw.
+@item
+Assigning NULL to @code{environ} to clear all variables is not
+portable; better is to assign @code{environ} to one-element array
+containing a NULL pointer.  That said, an empty environment is not
+portable either, as some systems may require particular environment
+variables (such as @code{PATH}) to be present in order to operate
+consistently.
 @end itemize