bpo-36352: Clarify fileutils.h documentation (GH-12406)

The last parameter of _Py_wreadlink(), _Py_wrealpath() and
_Py_wgetcwd() is a length, not a size: number of characters including
the trailing NUL character.

Enhance also documentation of error conditions.

1 files changed, 9 insertions, 3 deletions

diff --git a/Include/fileutils.h b/Include/fileutils.h
index 830e56a..0be8b0a 100644
--- a/Include/fileutils.h
+++ b/Include/fileutils.h
@@ -140,19 +140,25 @@ PyAPI_FUNC(Py_ssize_t) _Py_write_noraise(
 PyAPI_FUNC(int) _Py_wreadlink(
     const wchar_t *path,
     wchar_t *buf,
-    size_t bufsiz);
+    /* Number of characters of 'buf' buffer
+       including the trailing NUL character */
+    size_t buflen);
 #endif
 
 #ifdef HAVE_REALPATH
 PyAPI_FUNC(wchar_t*) _Py_wrealpath(
     const wchar_t *path,
     wchar_t *resolved_path,
-    size_t resolved_path_size);
+    /* Number of characters of 'resolved_path' buffer
+       including the trailing NUL character */
+    size_t resolved_path_len);
 #endif
 
 PyAPI_FUNC(wchar_t*) _Py_wgetcwd(
     wchar_t *buf,
-    size_t size);
+    /* Number of characters of 'buf' buffer
+       including the trailing NUL character */
+    size_t buflen);
 
 PyAPI_FUNC(int) _Py_get_inheritable(int fd);