Module Name: src
Committed By: uwe
Date: Fri Aug 16 18:35:19 UTC 2024
Modified Files:
src/lib/libc/locale: c8rtomb.3 mbrtoc8.3
Log Message:
c8rtomb(3), mbrtoc8(3): brush up markup
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/lib/libc/locale/c8rtomb.3 \
src/lib/libc/locale/mbrtoc8.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.1 src/lib/libc/locale/c8rtomb.3:1.2
--- src/lib/libc/locale/c8rtomb.3:1.1 Thu Aug 15 21:19:45 2024
+++ src/lib/libc/locale/c8rtomb.3 Fri Aug 16 18:35:19 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: c8rtomb.3,v 1.1 2024/08/15 21:19:45 riastradh Exp $
+.\" $NetBSD: c8rtomb.3,v 1.2 2024/08/16 18:35:19 uwe Exp $
.\"
.\" Copyright (c) 2024 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -36,11 +36,15 @@
.Lb libc
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SYNOPSIS
+.
.In uchar.h
+.
.Ft size_t
-.Fn c8rtomb "char * restrict s" \
-"char8_t c8" \
-"mbstate_t * restrict ps"
+.Fo c8rtomb
+.Fa "char * restrict s"
+.Fa "char8_t c8"
+.Fa "mbstate_t * restrict ps"
+.Fc
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh DESCRIPTION
The
@@ -93,23 +97,23 @@ NUL-terminate it, and print it:
char8_t c8[] = { 0xf0, 0x9f, 0x92, 0xa9 };
char buf[__arraycount(c8)*MB_CUR_MAX + 1], *s = buf;
size_t i;
-mbstate_t mbs = {0}; /* initial conversion state */
+mbstate_t mbs = {0}; /* initial conversion state */
for (i = 0; i < __arraycount(c8); i++) {
- size_t len;
+ size_t len;
- len = c8rtomb(s, c8[i], &mbs);
- if (len == (size_t)-1)
- err(1, "c8rtomb");
- assert(len < sizeof(buf) - (s - buf));
- s += len;
+ len = c8rtomb(s, c8[i], &mbs);
+ if (len == (size_t)-1)
+ err(1, "c8rtomb");
+ assert(len < sizeof(buf) - (s - buf));
+ s += len;
}
-*s = '\e0'; /* NUL-terminate */
+*s = '\e0'; /* NUL-terminate */
printf("%s\en", buf);
.Ed
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh ERRORS
-.Bl -tag -width ".Bq Er EILSEQ"
+.Bl -tag -width Bq
.It Bq Er EILSEQ
A surrogate code point was passed as
.Fa c8
@@ -177,7 +181,7 @@ in the standard which suggests that pass
should unconditionally store a null byte and reset
.Fa ps
to the initial conversion state:
-.Bd -offset indent
+.Bd -filled -offset indent
If
.Fa c8
is a null character, a null byte is stored, preceded by any shift
Index: src/lib/libc/locale/mbrtoc8.3
diff -u src/lib/libc/locale/mbrtoc8.3:1.1 src/lib/libc/locale/mbrtoc8.3:1.2
--- src/lib/libc/locale/mbrtoc8.3:1.1 Thu Aug 15 21:19:45 2024
+++ src/lib/libc/locale/mbrtoc8.3 Fri Aug 16 18:35:19 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: mbrtoc8.3,v 1.1 2024/08/15 21:19:45 riastradh Exp $
+.\" $NetBSD: mbrtoc8.3,v 1.2 2024/08/16 18:35:19 uwe Exp $
.\"
.\" Copyright (c) 2024 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -36,12 +36,16 @@
.Lb libc
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SYNOPSIS
+.
.In uchar.h
+.
.Ft size_t
-.Fn mbrtoc8 "char8_t * restrict pc8" \
-"const char * restrict s" \
-"size_t n" \
-"mbstate_t * restrict ps"
+.Fo mbrtoc8
+.Fa "char8_t * restrict pc8"
+.Fa "const char * restrict s"
+.Fa "size_t n"
+.Fa "mbstate_t * restrict ps"
+.Fc
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh DESCRIPTION
The
@@ -157,13 +161,16 @@ uses an internal
.Vt mbstate_t
object with static storage duration, distinct from all other
.Vt mbstate_t
-objects (including those used by
+objects
+.Po
+including those used by
.Xr mbrtoc16 3 ,
.Xr mbrtoc32 3 ,
.Xr c8rtomb 3 ,
.Xr c16rtomb 3 ,
and
-.Xr c32rtomb 3 ) ,
+.Xr c32rtomb 3
+.Pc ,
which is initialized at program startup to the initial conversion
state.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -171,20 +178,20 @@ state.
The
.Nm
function returns:
-.Bl -tag -width ".Li (size_t)-3" -offset indent
+.Bl -tag -width Li
.It Li 0
-[null]
+.Bq null
if within the next
.Fa n
bytes at
.Fa s
the first multibyte character is null.
-.It Fa i
-[code unit]
+.It Ar i
+.Bq code unit
where
.Li 0
\*(Le
-.Fa i
+.Ar i
\*(Le
.Fa n ,
if either
@@ -194,12 +201,12 @@ is in the initial conversion state or th
with
.Fa ps
had not yielded an incomplete UTF-8 code unit, and within the first
-.Fa i
+.Ar i
bytes at
.Fa s
a Unicode scalar value was decoded.
.It Li (size_t)-3
-[continuation]
+.Bq continuation
if the previous call to
.Nm
with
@@ -208,7 +215,7 @@ had yielded an incomplete UTF-8 code uni
outside the US-ASCII range; no additional input is consumed in this
case.
.It Li (size_t)-2
-[incomplete]
+.Bq incomplete
if either
.Fa ps
is in the initial conversion state or the previous call to
@@ -222,7 +229,7 @@ bytes at
including any previously buffered input, no complete Unicode scalar
value could be decoded.
.It Li (size_t)-1
-[error]
+.Bq error
if any encoding error was detected;
.Xr errno 2
is set to reflect the error.
@@ -233,37 +240,37 @@ Print the UTF-8 code units of a multibyt
.Bd -literal -offset indent
char *s = ...;
size_t n = ...;
-mbstate_t mbs = {0}; /* initial conversion state */
+mbstate_t mbs = {0}; /* initial conversion state */
while (n) {
- char8_t c8;
- size_t len;
+ char8_t c8;
+ size_t len;
- len = mbrtoc8(&c8, s, n, &mbs);
- switch (len) {
- case 0: /* null terminator */
- assert(c8 == '\e0');
- goto out;
- default: /* consumed input and yielded a byte c8 */
- printf("0x%02hhx\en", c8);
- break;
- case (size_t)-3: /* yielded a pending byte c8 */
- printf("continue 0x%02hhx\en", c8);
- break;
- case (size_t)-2: /* incomplete */
- printf("incomplete\en");
- goto readmore;
- case (size_t)-1: /* error */
- printf("error: %d\en", errno);
- goto out;
- }
- s += len;
- n -= len;
+ len = mbrtoc8(&c8, s, n, &mbs);
+ switch (len) {
+ case 0: /* null terminator */
+ assert(c8 == '\e0');
+ goto out;
+ default: /* consumed input and yielded a byte c8 */
+ printf("0x%02hhx\en", c8);
+ break;
+ case (size_t)-3: /* yielded a pending byte c8 */
+ printf("continue 0x%02hhx\en", c8);
+ break;
+ case (size_t)-2: /* incomplete */
+ printf("incomplete\en");
+ goto readmore;
+ case (size_t)-1: /* error */
+ printf("error: %d\en", errno);
+ goto out;
+ }
+ s += len;
+ n -= len;
}
.Ed
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh ERRORS
-.Bl -tag -width ".Bq Er EILSEQ"
+.Bl -tag -width Bq
.It Bq Er EILSEQ
The multibyte sequence cannot be decoded as a Unicode scalar value.
.It Bq Er EIO
