diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index c41ee1b..6ad4785 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -107,6 +107,10 @@
    to modify the environment as well as query the environment.  :func:`putenv` will
    be called automatically when the mapping is modified.
 
+   On Unix, keys and values use :func:`sys.getfilesystemencoding` and
+   ``'surrogateescape'`` error handler. Use :data:`environb` if you would like
+   to use a different encoding.
+
    .. note::
 
       Calling :func:`putenv` directly does not change ``os.environ``, so it's better
@@ -128,6 +132,16 @@
    one of the :meth:`pop` or :meth:`clear` methods is called.
 
 
+.. data:: environb
+
+   Bytes version of :data:`environ`: a mapping object representing the
+   environment as byte strings. :data:`environ` and :data:`environb` are
+   synchronized (modify :data:`environb` updates :data:`environ`, and vice
+   versa).
+
+   Availability: Unix.
+
+
 .. function:: chdir(path)
               fchdir(fd)
               getcwd()
@@ -251,7 +265,19 @@
 .. function:: getenv(key, default=None)
 
    Return the value of the environment variable *key* if it exists, or
-   *default* if it doesn't.  Availability: most flavors of Unix, Windows.
+   *default* if it doesn't. *key*, *default* and the result are str.
+   Availability: most flavors of Unix, Windows.
+
+   On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding`
+   and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
+   would like to use a different encoding.
+
+
+.. function:: getenvb(key, default=None)
+
+   Return the value of the environment variable *key* if it exists, or
+   *default* if it doesn't. *key*, *default* and the result are bytes.
+   Availability: most flavors of Unix.
 
 
 .. function:: putenv(key, value)
diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst
index c33d9e5..d65b999 100644
--- a/Doc/library/posix.rst
+++ b/Doc/library/posix.rst
@@ -69,17 +69,22 @@
 .. data:: environ
 
    A dictionary representing the string environment at the time the interpreter
-   was started.  For example, ``environ['HOME']`` is the pathname of your home
-   directory, equivalent to ``getenv("HOME")`` in C.
+   was started. Keys and values are bytes on Unix and str on Windows. For
+   example, ``environ[b'HOME']`` (``environ['HOME']`` on Windows) is the
+   pathname of your home directory, equivalent to ``getenv("HOME")`` in C.
 
    Modifying this dictionary does not affect the string environment passed on by
    :func:`execv`, :func:`popen` or :func:`system`; if you need to change the
    environment, pass ``environ`` to :func:`execve` or add variable assignments and
    export statements to the command string for :func:`system` or :func:`popen`.
 
+   .. versionchanged:: 3.2
+      On Unix, keys and values are bytes.
+
    .. note::
 
-      The :mod:`os` module provides an alternate implementation of ``environ`` which
-      updates the environment on modification.  Note also that updating ``os.environ``
-      will render this dictionary obsolete.  Use of the :mod:`os` module version of
-      this is recommended over direct access to the :mod:`posix` module.
+      The :mod:`os` module provides an alternate implementation of ``environ``
+      which updates the environment on modification. Note also that updating
+      :data:`os.environ` will render this dictionary obsolete. Use of the
+      :mod:`os` module version of this is recommended over direct access to the
+      :mod:`posix` module.