Issue #29157: enhance py_getrandom() documentation
diff --git a/Python/random.c b/Python/random.c
index bc96226..c97d5e7 100644
--- a/Python/random.c
+++ b/Python/random.c
@@ -82,14 +82,18 @@
#if defined(HAVE_GETRANDOM) || defined(HAVE_GETRANDOM_SYSCALL)
#define PY_GETRANDOM 1
-/* Call getrandom()
+/* Call getrandom() to get random bytes:
+
- Return 1 on success
- - Return 0 if getrandom() syscall is not available (failed with ENOSYS or
- EPERM) or if getrandom(GRND_NONBLOCK) failed with EAGAIN (system urandom
- not initialized yet) and raise=0.
+ - Return 0 if getrandom() is not available (failed with ENOSYS or EPERM),
+ or if getrandom(GRND_NONBLOCK) failed with EAGAIN (system urandom not
+ initialized yet) and raise=0.
- Raise an exception (if raise is non-zero) and return -1 on error:
- getrandom() failed with EINTR and the Python signal handler raised an
- exception, or getrandom() failed with a different error. */
+ if getrandom() failed with EINTR, raise is non-zero and the Python signal
+ handler raised an exception, or if getrandom() failed with a different
+ error.
+
+ getrandom() is retried if it failed with EINTR: interrupted by a signal. */
static int
py_getrandom(void *buffer, Py_ssize_t size, int blocking, int raise)
{
@@ -110,7 +114,8 @@
while (0 < size) {
#ifdef sun
/* Issue #26735: On Solaris, getrandom() is limited to returning up
- to 1024 bytes */
+ to 1024 bytes. Call it multiple times if more bytes are
+ requested. */
n = Py_MIN(size, 1024);
#else
n = Py_MIN(size, LONG_MAX);
@@ -141,18 +146,19 @@
#endif
if (n < 0) {
- /* ENOSYS: getrandom() syscall not supported by the kernel (but
- * maybe supported by the host which built Python). EPERM:
- * getrandom() syscall blocked by SECCOMP or something else. */
+ /* ENOSYS: the syscall is not supported by the kernel.
+ EPERM: the syscall is blocked by a security policy (ex: SECCOMP)
+ or something else. */
if (errno == ENOSYS || errno == EPERM) {
getrandom_works = 0;
return 0;
}
/* getrandom(GRND_NONBLOCK) fails with EAGAIN if the system urandom
- is not initialiazed yet. For _PyRandom_Init(), we ignore their
+ is not initialiazed yet. For _PyRandom_Init(), we ignore the
error and fall back on reading /dev/urandom which never blocks,
- even if the system urandom is not initialized yet. */
+ even if the system urandom is not initialized yet:
+ see the PEP 524. */
if (errno == EAGAIN && !raise && !blocking) {
return 0;
}
@@ -313,9 +319,10 @@
fd = _Py_open("/dev/urandom", O_RDONLY);
if (fd < 0) {
if (errno == ENOENT || errno == ENXIO ||
- errno == ENODEV || errno == EACCES)
+ errno == ENODEV || errno == EACCES) {
PyErr_SetString(PyExc_NotImplementedError,
"/dev/urandom (or equivalent) not found");
+ }
/* otherwise, keep the OSError exception raised by _Py_open() */
return -1;
}