bpo-36333: Clarify fileutils.h documentation

[vstinner]

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.

https://bugs.python.org/issue36333

[matrixise]

LGTM

[serhiy-storchaka]

To me, length is the number of characters not including the trailing NUL character, and size is the number of characters including the trailing NUL character.

This change looks confusing to me.

[vstinner]

To me, length is the number of characters not including the trailing NUL character, and size is the number of characters including the trailing NUL character.

Oh. I tried but I failed to find a clear "definition" of "length" vs "size". Usually for me, on a wchar_t* string, size means the number of bytes: wcslen(str)*sizeof(wchar_t), whereas length means the number of characters excluding trainling NUL: wcslen(str).

In fact, I don't know any exact term for "length including trailing NUL". That's why I added doc to be more explicit about that.

Since this PR, I also modified getpath.c to handle differently buffer length/size. I added functions which take Py_ARRAY_LENGTH(buffer) to decide if an operation will overflow a string or not.