Module Name: src
Committed By: riastradh
Date: Sat Aug 17 00:32:19 UTC 2024
Modified Files:
src/lib/libc/locale: c8rtomb.3
Log Message:
c8rtomb(3): Clarify prose and fix example in caveat.
PR standards/58601: uchar.h C23 compliance: char8_t, mbrtoc8, c8rtomb
To generate a diff of this commit:
cvs rdiff -u -r1.4 -r1.5 src/lib/libc/locale/c8rtomb.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/locale/c8rtomb.3
diff -u src/lib/libc/locale/c8rtomb.3:1.4 src/lib/libc/locale/c8rtomb.3:1.5
--- src/lib/libc/locale/c8rtomb.3:1.4 Fri Aug 16 23:34:25 2024
+++ src/lib/libc/locale/c8rtomb.3 Sat Aug 17 00:32:19 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: c8rtomb.3,v 1.4 2024/08/16 23:34:25 riastradh Exp $
+.\" $NetBSD: c8rtomb.3,v 1.5 2024/08/17 00:32:19 riastradh Exp $
.\"
.\" Copyright (c) 2024 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -30,7 +30,7 @@
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh NAME
.Nm c8rtomb
-.Nd Restartable UTF-8 code unit to multibyte conversion
+.Nd Restartable UTF-8 to multibyte conversion
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh LIBRARY
.Lb libc
@@ -49,37 +49,52 @@
.Sh DESCRIPTION
The
.Nm
-function attempts to encode Unicode input as a multibyte character
-sequence output at
-.Fa s
-in the current locale, writing anywhere between zero and
-.Dv MB_CUR_MAX
-bytes, inclusive, to
-.Fa s ,
-depending on the inputs and conversion state
-.Fa ps .
+function decodes UTF-8 and converts it to multibyte characters in the
+current locale, keeping state so it can restart after incremental
+progress.
.Pp
-The input
-.Fa c8
-is a UTF-8 code unit.
-Successive calls to
+Each call to
.Nm
-must provide well-formed UTF-8 code unit sequences.
-If
+updates the conversion state
+.Fa ps
+with a UTF-8 code unit
.Fa c8 ,
-when appended to the sequence of code units passed in previous calls
+writes up to
+.Dv MB_CUR_MAX
+bytes to
+.Fa s
+(possibly none), and returns either the number of bytes written to
+.Fa s
+or
+.Li (size_t)-1
+to denote error.
+.Pp
+Over successive calls to
+.Nm
with the same state
.Fa ps ,
+the sequence of
+.Fa c8
+values must be a well-formed UTF-8 code unit sequence.
+If
+.Fa c8 ,
+when appended to the sequence of code units passed in previous calls,
does not form a well-formed UTF-8 code unit sequence, then
.Nm
-will return
+returns
.Li (size_t)-1
-to denote failure with
+with
.Xr errno 2
set to
.Er EILSEQ .
.Pp
If
+.Fa s
+is a null pointer, no output is stored, but the effects on
+.Fa ps
+and the return value are unchanged.
+.Pp
+If
.Fa ps
is a null pointer,
.Nm
@@ -191,14 +206,14 @@ followed by a NUL:
c8rtomb(s, 0xf0, ps);
c8rtomb(s, 0x9f, ps);
c8rtomb(s, 0x92, ps);
-c8rtomb(s, L'\e0', ps);
+c8rtomb(s, '\e0', ps);
.Ed
.Pp
Currently this fails with
.Er EILSEQ
which matches other implementations, but this is at odds with language
in the standard which suggests that passing
-.Li L'\e0'
+.Li '\e0'
should unconditionally store a null byte and reset
.Fa ps
to the initial conversion state:
