| .\" Copyright (c) Bruno Haible <haible@clisp.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's Single UNIX specification http://www.UNIX-systems.org/online.html |
| .\" ISO/IEC 9899:1999 |
| .\" |
| .TH WCSTOMBS 3 2021-03-22 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| wcstombs \- convert a wide-character string to a multibyte string |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdlib.h> |
| .PP |
| .BI "size_t wcstombs(char *restrict " dest ", const wchar_t *restrict " src , |
| .BI " size_t " n ); |
| .fi |
| .SH DESCRIPTION |
| If |
| .I dest |
| is not NULL, the |
| .BR wcstombs () |
| function converts |
| the wide-character string |
| .I src |
| to a multibyte string starting at |
| .IR dest . |
| At most |
| .I n |
| bytes are written to |
| .IR dest . |
| The sequence of characters placed in |
| .IR dest |
| begins in the initial shift state. |
| The conversion can stop for three reasons: |
| .IP 1. 3 |
| A wide character has been encountered that can not be represented as a |
| multibyte sequence (according to the current locale). |
| In this case, |
| .I (size_t)\ \-1 |
| is returned. |
| .IP 2. |
| The length limit forces a stop. |
| In this case, the number of bytes written to |
| .I dest |
| is returned, but the shift state at this point is lost. |
| .IP 3. |
| The wide-character string has been completely converted, including the |
| terminating null wide character (L\(aq\e0\(aq). |
| In this case, the conversion ends in the initial shift state. |
| The number of bytes written to |
| .IR dest , |
| excluding the terminating null byte (\(aq\e0\(aq), is returned. |
| .PP |
| The programmer must ensure that there is room for at least |
| .I n |
| bytes |
| at |
| .IR dest . |
| .PP |
| If |
| .IR dest |
| is NULL, |
| .I n |
| is ignored, and the conversion proceeds as |
| above, except that the converted bytes are not written out to memory, |
| and no length limit exists. |
| .PP |
| In order to avoid the case 2 above, the programmer should make sure |
| .I n |
| is greater than or equal to |
| .IR "wcstombs(NULL,src,0)+1" . |
| .SH RETURN VALUE |
| The |
| .BR wcstombs () |
| function returns the number of bytes that make up the |
| converted part of a multibyte sequence, |
| not including the terminating null byte. |
| If a wide character was encountered which could not be |
| converted, |
| .I (size_t)\ \-1 |
| is returned. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR wcstombs () |
| T} Thread safety MT-Safe |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, C99. |
| .SH NOTES |
| The behavior of |
| .BR wcstombs () |
| depends on the |
| .B LC_CTYPE |
| category of the |
| current locale. |
| .PP |
| The function |
| .BR wcsrtombs (3) |
| provides a better interface to the same functionality. |
| .SH SEE ALSO |
| .BR mblen (3), |
| .BR mbstowcs (3), |
| .BR mbtowc (3), |
| .BR wcsrtombs (3), |
| .BR wctomb (3) |