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

3 files changed, 20 insertions, 6 deletions

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