From: Andriy Utkin <andriy_utkin@fastmail.com>
To: Alejandro Colomar <alx@kernel.org>
Cc: linux-man@vger.kernel.org, Andriy Utkin <andriy_utkin@fastmail.com>
Subject: [PATCH] mbsrtowcs.3: add a note for conversion completion
Date: Mon, 13 Nov 2023 13:48:57 +0000 [thread overview]
Message-ID: <20231113134857.1639387-1-andriy_utkin@fastmail.com> (raw)
This adds a note to resolve a confusion I had.
Maintainers are most welcome to improve my wording.
I aimed for this function to work in such a manner so that
it would convert the entire string. So I allocated a destination buffer
to accommodate the string length in wide charaters and the terminating
null. The function was called with len equal to the length of the string
in wide characters, as returned by mbsrtowcs(NULL, ...).
This resulted in *src being updated to point at the trailing null
character, rather than NULL which I expected.
Here is an example which illustrates the point:
Code:
#include <wchar.h>
#include <stdio.h>
int main(void) {
const char *src = "Hello", *s1 = src, *s2 = src;
wchar_t dest[6];
int ret;
printf("src is %p\n", src);
ret = mbsrtowcs(NULL, &src, 0, NULL);
printf("mbsrtowcs(src=NULL) returned %d\n", ret);
ret = mbsrtowcs(dest, &s1, 5, NULL);
printf("mbsrtowcs(len=5) returned %d, updated src is %p\n", ret, s1);
ret = mbsrtowcs(dest, &s2, 6, NULL);
printf("mbsrtowcs(len=6) returned %d, updated src is %p\n", ret, s2);
return 0;
}
Output:
src is 0x402010
mbsrtowcs(src=NULL) returned 5
mbsrtowcs(len=5) returned 5, updated src is 0x402015
mbsrtowcs(len=6) returned 5, updated src is (nil)
---
man3/mbsrtowcs.3 | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/man3/mbsrtowcs.3 b/man3/mbsrtowcs.3
index 11741d187..4718b335d 100644
--- a/man3/mbsrtowcs.3
+++ b/man3/mbsrtowcs.3
@@ -155,6 +155,15 @@ current locale.
Passing NULL as
.I ps
is not multithread safe.
+.P
+Calling this function with
+.I len
+set to the value returned from
+.I mbsrtowcs(NULL, ...)
+behaves according to scenario #2 described above:
+.I *src
+is set to the address of the terminating null wide character, rather than to NULL.
+Add 1 to that value for it to work according to scenario #3 (complete conversion).
.SH SEE ALSO
.BR iconv (3),
.BR mbrtowc (3),
--
2.41.0
next reply other threads:[~2023-11-13 13:49 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-11-13 13:48 Andriy Utkin [this message]
2023-11-14 9:21 ` [PATCH] mbsrtowcs.3: add a note for conversion completion Alejandro Colomar
2023-11-14 9:47 ` Andriy Utkin
2023-11-14 10:04 ` Alejandro Colomar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20231113134857.1639387-1-andriy_utkin@fastmail.com \
--to=andriy_utkin@fastmail.com \
--cc=alx@kernel.org \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).