| Functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Wide/multibyte conversions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
(C95) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Types | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Macros | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Defined in header <stdlib.h> | ||
| (1) | ||
| (until C99) | ||
| (since C99) | ||
errno_t wcstombs_s(size_t*restrict retval,char*restrict dst, rsize_t dstsz, constwchar_t*restrict src, rsize_t len); | (2) | (since C11) |
src to its narrow multibyte representation that begins in the initial shift state. Converted characters are stored in the successive elements of the char array pointed to bydst. No more thanlen bytes are written to the destination array.len.src anddst overlap, the behavior is unspecified.retvaldst, which may bedst[len] ordst[dstsz], whichever comes first (meaning up to len+1/dstsz+1 total bytes may be written). In this case, there may be no unshift sequence written before the terminating null.dst is a null pointer, the number of bytes that would be produced is stored in*retvaldstszsrc anddst overlap, the behavior is unspecified.retval orsrc is a null pointerdstsz orlen is greater thanRSIZE_MAX (unlessdst is null)dstsz is not zero (unlessdst is null)len is greater thandstsz and the conversion does not encounter null or encoding error in thesrc array by the timedstsz is reached (unlessdst is null)wcstombs_s is only guaranteed to be available if__STDC_LIB_EXT1__ is defined by the implementation and if the user defines__STDC_WANT_LIB_EXT1__ to the integer constant1 before including<stdlib.h>.Contents |
In most implementations,wcstombs updates a global static object of typembstate_t as it processes through the string, and cannot be called simultaneously by two threads,wcsrtombs orwcstombs_s should be used in such cases.
POSIX specifies a common extension: ifdst is a null pointer, this function returns the number of bytes that would be written todst, if converted. Similar behavior is standard forwcsrtombs andwcstombs_s.
| dst | - | pointer to narrow character array where the multibyte character will be stored |
| src | - | pointer to the first element of a null-terminated wide string to convert |
| len | - | number of bytes available in the array pointed to by dst |
| dstsz | - | max number of bytes that will be written (size of thedst array) |
| retval | - | pointer to a size_t object where the result will be stored |
dst. On conversion error (if invalid wide character was encountered), returns(size_t)-1.dst, is stored in*retval), non-zero on error. In case of a runtime constraint violation, stores(size_t)-1 in*retval (unlessretval is null) and setsdst[0] to'\0' (unlessdst is null ordstmax is zero or greater thanRSIZE_MAX)#include <stdio.h>#include <stdlib.h>#include <locale.h> int main(void){// 4 wide charactersconstwchar_t src[]= L"z\u00df\u6c34\U0001f34c";// they occupy 10 bytes in UTF-8char dst[11]; setlocale(LC_ALL,"en_US.utf8");printf("wide-character string: '%ls'\n",src);for(size_t ndx=0; ndx<sizeof src/sizeof src[0];++ndx)printf(" src[%2zu] = %#8x\n", ndx, src[ndx]); int rtn_val= wcstombs(dst, src,sizeof dst);printf("rtn_val = %d\n", rtn_val);if(rtn_val>0)printf("multibyte string: '%s'\n",dst);for(size_t ndx=0; ndx<sizeof dst;++ndx)printf(" dst[%2zu] = %#2x\n", ndx,(unsignedchar)dst[ndx]);}
Output:
wide-character string: 'zß水🍌' src[ 0] = 0x7a src[ 1] = 0xdf src[ 2] = 0x6c34 src[ 3] = 0x1f34c src[ 4] = 0rtn_val = 10multibyte string: 'zß水🍌' dst[ 0] = 0x7a dst[ 1] = 0xc3 dst[ 2] = 0x9f dst[ 3] = 0xe6 dst[ 4] = 0xb0 dst[ 5] = 0xb4 dst[ 6] = 0xf0 dst[ 7] = 0x9f dst[ 8] = 0x8d dst[ 9] = 0x8c dst[10] = 0
(C95)(C11) | converts a wide string to narrow multibyte character string, given state (function)[edit] |
(C11) | converts a narrow multibyte character string to wide string (function)[edit] |
C++ documentation forwcstombs | |
