#2084: document limitations of environ() on macOS Big Sur

5 files changed, 30 insertions, 7 deletions

diff --git a/docs/conf.py b/docs/conf.py
index f4a32b98..f0de7772 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -96,7 +96,7 @@ release = VERSION
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "eng"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
diff --git a/docs/index.rst b/docs/index.rst
index aa0fd932..19961103 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1202,6 +1202,11 @@ Process class
     >>> psutil.Process().environ()
     {'LC_NUMERIC': 'it_IT.UTF-8', 'QT_QPA_PLATFORMTHEME': 'appmenu-qt5', 'IM_CONFIG_PHASE': '1', 'XDG_GREETER_DATA_DIR': '/var/lib/lightdm-data/giampaolo', 'GNOME_DESKTOP_SESSION_ID': 'this-is-deprecated', 'XDG_CURRENT_DESKTOP': 'Unity', 'UPSTART_EVENTS': 'started starting', 'GNOME_KEYRING_PID': '', 'XDG_VTNR': '7', 'QT_IM_MODULE': 'ibus', 'LOGNAME': 'giampaolo', 'USER': 'giampaolo', 'PATH': '/home/giampaolo/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/giampaolo/svn/sysconf/bin', 'LC_PAPER': 'it_IT.UTF-8', 'GNOME_KEYRING_CONTROL': '', 'GTK_IM_MODULE': 'ibus', 'DISPLAY': ':0', 'LANG': 'en_US.UTF-8', 'LESS_TERMCAP_se': '\x1b[0m', 'TERM': 'xterm-256color', 'SHELL': '/bin/bash', 'XDG_SESSION_PATH': '/org/freedesktop/DisplayManager/Session0', 'XAUTHORITY': '/home/giampaolo/.Xauthority', 'LANGUAGE': 'en_US', 'COMPIZ_CONFIG_PROFILE': 'ubuntu', 'LC_MONETARY': 'it_IT.UTF-8', 'QT_LINUX_ACCESSIBILITY_ALWAYS_ON': '1', 'LESS_TERMCAP_me': '\x1b[0m', 'LESS_TERMCAP_md': '\x1b[01;38;5;74m', 'LESS_TERMCAP_mb': '\x1b[01;31m', 'HISTSIZE': '100000', 'UPSTART_INSTANCE': '', 'CLUTTER_IM_MODULE': 'xim', 'WINDOWID': '58786407', 'EDITOR': 'vim', 'SESSIONTYPE': 'gnome-session', 'XMODIFIERS': '@im=ibus', 'GPG_AGENT_INFO': '/home/giampaolo/.gnupg/S.gpg-agent:0:1', 'HOME': '/home/giampaolo', 'HISTFILESIZE': '100000', 'QT4_IM_MODULE': 'xim', 'GTK2_MODULES': 'overlay-scrollbar', 'XDG_SESSION_DESKTOP': 'ubuntu', 'SHLVL': '1', 'XDG_RUNTIME_DIR': '/run/user/1000', 'INSTANCE': 'Unity', 'LC_ADDRESS': 'it_IT.UTF-8', 'SSH_AUTH_SOCK': '/run/user/1000/keyring/ssh', 'VTE_VERSION': '4205', 'GDMSESSION': 'ubuntu', 'MANDATORY_PATH': '/usr/share/gconf/ubuntu.mandatory.path', 'VISUAL': 'vim', 'DESKTOP_SESSION': 'ubuntu', 'QT_ACCESSIBILITY': '1', 'XDG_SEAT_PATH': '/org/freedesktop/DisplayManager/Seat0', 'LESSCLOSE': '/usr/bin/lesspipe %s %s', 'LESSOPEN': '| /usr/bin/lesspipe %s', 'XDG_SESSION_ID': 'c2', 'DBUS_SESSION_BUS_ADDRESS': 'unix:abstract=/tmp/dbus-9GAJpvnt8r', '_': '/usr/bin/python', 'DEFAULTS_PATH': '/usr/share/gconf/ubuntu.default.path', 'LC_IDENTIFICATION': 'it_IT.UTF-8', 'LESS_TERMCAP_ue': '\x1b[0m', 'UPSTART_SESSION': 'unix:abstract=/com/ubuntu/upstart-session/1000/1294', 'XDG_CONFIG_DIRS': '/etc/xdg/xdg-ubuntu:/usr/share/upstart/xdg:/etc/xdg', 'GTK_MODULES': 'gail:atk-bridge:unity-gtk-module', 'XDG_SESSION_TYPE': 'x11', 'PYTHONSTARTUP': '/home/giampaolo/.pythonstart', 'LC_NAME': 'it_IT.UTF-8', 'OLDPWD': '/home/giampaolo/svn/curio_giampaolo/tests', 'GDM_LANG': 'en_US', 'LC_TELEPHONE': 'it_IT.UTF-8', 'HISTCONTROL': 'ignoredups:erasedups', 'LC_MEASUREMENT': 'it_IT.UTF-8', 'PWD': '/home/giampaolo/svn/curio_giampaolo', 'JOB': 'gnome-session', 'LESS_TERMCAP_us': '\x1b[04;38;5;146m', 'UPSTART_JOB': 'unity-settings-daemon', 'LC_TIME': 'it_IT.UTF-8', 'LESS_TERMCAP_so': '\x1b[38;5;246m', 'PAGER': 'less', 'XDG_DATA_DIRS': '/usr/share/ubuntu:/usr/share/gnome:/usr/local/share/:/usr/share/:/var/lib/snapd/desktop', 'XDG_SEAT': 'seat0'}
 
+    .. note::
+      on macOS Big Sur this function returns something meaningful only for the
+      current process or in
+      `other specific circumstances <https://github.com/apple/darwin-xnu/blob/2ff845c2e033bd0ff64b5b6aa6063a1f8f65aa32/bsd/kern/kern_sysctl.c#L1315-L1321>`__).
+
     .. versionadded:: 4.0.0
     .. versionchanged:: 5.3.0 added SunOS support
     .. versionchanged:: 5.6.3 added AIX support
@@ -2625,6 +2630,10 @@ Supported Python versions are 2.7, 3.4+ and PyPy3.
 Timeline
 ========
 
+- 2022-09-04:
+  `5.9.2 <https://pypi.org/project/psutil/5.9.2/#files>`__ -
+  `what's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst#592>`__ -
+  `diff <https://github.com/giampaolo/psutil/compare/release-5.9.1...release-5.9.2#files_bucket>`__
 - 2022-05-20:
   `5.9.1 <https://pypi.org/project/psutil/5.9.1/#files>`__ -
   `what's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst#591>`__ -
diff --git a/psutil/_psutil_osx.c b/psutil/_psutil_osx.c
index cd375bab..f634be36 100644
--- a/psutil/_psutil_osx.c
+++ b/psutil/_psutil_osx.c
@@ -405,18 +405,24 @@ psutil_proc_cmdline(PyObject *self, PyObject *args) {
 
 /*
  * Return process environment as a Python string.
+ * On Big Sur this function returns an empty string unless:
+ * * kernel is DEVELOPMENT || DEBUG
+ * * target process is same as current_proc()
+ * * target process is not cs_restricted
+ * * SIP is off
+ * * caller has an entitlement
  */
 static PyObject *
 psutil_proc_environ(PyObject *self, PyObject *args) {
     pid_t pid;
-    PyObject *py_retdict = NULL;
+    PyObject *py_str = NULL;
 
     if (! PyArg_ParseTuple(args, _Py_PARSE_PID, &pid))
         return NULL;
 
     // get the environment block, defined in arch/osx/process_info.c
-    py_retdict = psutil_get_environ(pid);
-    return py_retdict;
+    py_str = psutil_get_environ(pid);
+    return py_str;
 }
 
 
diff --git a/psutil/arch/osx/process_info.c b/psutil/arch/osx/process_info.c
index 4af510e8..47330ea6 100644
--- a/psutil/arch/osx/process_info.c
+++ b/psutil/arch/osx/process_info.c
@@ -241,7 +241,14 @@ error:
 }
 
 
-// return process environment as a python string
+// Return process environment as a python string.
+// On Big Sur this function returns an empty string unless:
+// * kernel is DEVELOPMENT || DEBUG
+// * target process is same as current_proc()
+// * target process is not cs_restricted
+// * SIP is off
+// * caller has an entitlement
+// See: https://github.com/apple/darwin-xnu/blob/2ff845c2e033bd0ff64b5b6aa6063a1f8f65aa32/bsd/kern/kern_sysctl.c#L1315-L1321
 PyObject *
 psutil_get_environ(pid_t pid) {
     int nargs;
diff --git a/psutil/tests/test_contracts.py b/psutil/tests/test_contracts.py
index f4ace838..d376a338 100755
--- a/psutil/tests/test_contracts.py
+++ b/psutil/tests/test_contracts.py
@@ -34,6 +34,7 @@ from psutil import WINDOWS
 from psutil._compat import FileNotFoundError
 from psutil._compat import long
 from psutil._compat import range
+from psutil._compat import unicode
 from psutil.tests import APPVEYOR
 from psutil.tests import CI_TESTING
 from psutil.tests import GITHUB_ACTIONS
@@ -448,7 +449,7 @@ class TestFetchAllProcesses(PsutilTestCase):
             self.assertIsInstance(part, str)
 
     def exe(self, ret, info):
-        self.assertIsInstance(ret, (str, type(None)))
+        self.assertIsInstance(ret, (str, unicode, type(None)))
         if not ret:
             self.assertEqual(ret, '')
         else:
@@ -476,7 +477,7 @@ class TestFetchAllProcesses(PsutilTestCase):
         self.assertGreaterEqual(ret, 0)
 
     def name(self, ret, info):
-        self.assertIsInstance(ret, str)
+        self.assertIsInstance(ret, (str, unicode))
         if APPVEYOR and not ret and info['status'] == 'stopped':
             return
         # on AIX, "<exiting>" processes don't have names