https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=837780b918f1ee1b53a49fc26a011f255786c999
commit 837780b918f1ee1b53a49fc26a011f255786c999
Author: Jeremy Drake <cyg...@jdrake.com>
Date: Thu May 1 12:24:08 2025 -0700
Cygwin: docs: flesh out docs for cygwin_conv_path.
Explicitly specify that `from` and `to` are NUL-terminated strings, that
NULL is permitted in `to` when `size` is 0, and that `to` is not
written to in the event of an error (unless it was a fault while writing
to `to`).
Signed-off-by: Jeremy Drake <cyg...@jdrake.com>
Diff:
---
winsup/doc/path.xml | 21 ++++++++++++++-------
1 file changed, 14 insertions(+), 7 deletions(-)
diff --git a/winsup/doc/path.xml b/winsup/doc/path.xml
index f56614bb6..de1b95a37 100644
--- a/winsup/doc/path.xml
+++ b/winsup/doc/path.xml
@@ -33,12 +33,12 @@
<refsect1 id="func-cygwin-conv-path-desc">
<title>Description</title>
-<para>Use this function to convert POSIX paths in
-<parameter>from</parameter> to Win32 paths in <parameter>to</parameter>
-or, vice versa, Win32 paths in <parameter>from</parameter> to POSIX paths
-in <parameter>to</parameter>. <parameter>what</parameter>
-defines the direction of this conversion and can be any of the below
-values.</para>
+<para>Use this function to convert NUL-terminated POSIX paths in
+<parameter>from</parameter> to NUL-terminated Win32 paths in
+<parameter>to</parameter> or, vice versa, NUL-terminated Win32 paths in
+<parameter>from</parameter> to NUL-terminated POSIX paths in
+<parameter>to</parameter>. <parameter>what</parameter> defines the
+direction of this conversion and can be any of the below values.</para>
<programlisting>
CCP_POSIX_TO_WIN_A /* from is char *posix, to is char *win32 */
@@ -62,7 +62,8 @@ default.</para>
<para><parameter>size</parameter> is the size of the buffer pointed to
by <parameter>to</parameter> in bytes. If <parameter>size</parameter>
-is 0, <function>cygwin_conv_path</function> just returns the required
+is 0, <parameter>to</parameter> may be NULL and
+<function>cygwin_conv_path</function> just returns the required
buffer size in bytes. Otherwise, it returns 0 on success, or -1 on
error and errno is set to one of the below values.</para>
@@ -73,6 +74,12 @@ error and errno is set to one of the below values.</para>
of what == CCP_POSIX_TO_WIN_A, longer than MAX_PATH.
ENOSPC size is less than required for the conversion.
</programlisting>
+
+<para>In the event of an error, the memory at <parameter>to</parameter> is
+not modified unless the error is <constant>EFAULT</constant> writing to
+the memory at <parameter>to</parameter>, which may happen if
+<parameter>size</parameter> is incorrectly specified.
+
</refsect1>
<refsect1 id="func-cygwin-conv-path-example">
