Section (3) wcsrtombs
Name
wcsrtombs — convert a wide-character string to a multibyte string
Synopsis
#include <wchar.h>
size_t
wcsrtombs( |
char *dest, |
const wchar_t **src, | |
size_t len, | |
mbstate_t *ps) ; |
DESCRIPTION
If dest
is not
NULL, the wcsrtombs
() function
converts the wide-character string *src
to a multibyte string
starting at dest
. At
most len
bytes are
written to dest
. The
shift state *ps
is
updated. The conversion is effectively performed by
repeatedly calling wcrtomb(dest,
*src, ps), as long as this call succeeds, and
then incrementing dest
by the number of bytes
written and *src
by
one. The conversion can stop for three reasons:
-
A wide character has been encountered that can not be represented as a multibyte sequence (according to the current locale). In this case, *
src
is left pointing to the invalid wide character, (size_t) −1 is returned, anderrno
is set to EILSEQ. -
The length limit forces a stop. In this case, *
src
is left pointing to the next wide character to be converted, and the number of bytes written todest
is returned. -
The wide-character string has been completely converted, including the terminating null wide character (L_zsingle_quotesz_ _zsingle_quotesz_), which has the side effect of bringing back *
ps
to the initial state. In this case, *src
is set to NULL, and the number of bytes written todest
, excluding the terminating null byte (_zsingle_quotesz_ _zsingle_quotesz_), is returned.
If dest
is NULL,
len
is ignored, and
the conversion proceeds as above, except that the converted
bytes are not written out to memory, and that no length limit
exists.
In both of the above cases, if ps
is NULL, a static anonymous
state known only to the wcsrtombs
() function is used instead.
The programmer must ensure that there is room for at least
len
bytes at
dest
.
RETURN VALUE
The wcsrtombs
() function
returns the number of bytes that make up the converted part
of multibyte sequence, not including the terminating null
byte. If a wide character was encountered which could not be
converted, (size_t)
−1 is returned, and errno
set to EILSEQ.
ATTRIBUTES
For an explanation of the terms used in this section, see attributes(7).
Interface | Attribute | Value |
wcsrtombs () |
Thread safety | MT-Unsafe race:wcsrtombs/!ps |
NOTES
The behavior of wcsrtombs
()
depends on the LC_CTYPE
category of the current locale.
Passing NULL as ps
is not multithread safe.
COLOPHON
This page is part of release 5.04 of the Linux man-pages
project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
https://www.kernel.org/doc/man−pages/.
Copyright (c) Bruno Haible <haibleclisp.cons.org> %%%LICENSE_START(GPLv2+_DOC_ONEPARA) This is free documentation; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. %%%LICENSE_END References consulted: GNU glibc-2 source code and manual Dinkumware C library reference http://www.dinkumware.com/ OpenGroup_zsingle_quotesz_s Single UNIX specification http://www.UNIX-systems.org/online.html ISO/IEC 9899:1999 |