1.\" $OpenBSD: wcstombs.3,v 1.8 2022/03/29 18:15:52 naddy Exp $ 2.\" $NetBSD: wcstombs.3,v 1.5 2003/09/08 17:54:32 wiz Exp $ 3.\" 4.\" Copyright (c)2002 Citrus Project, 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd $Mdocdate: March 29 2022 $ 29.Dt WCSTOMBS 3 30.Os 31.\" ---------------------------------------------------------------------- 32.Sh NAME 33.Nm wcstombs 34.Nd converts a wide-character string to a multibyte character string 35.\" ---------------------------------------------------------------------- 36.Sh SYNOPSIS 37.In stdlib.h 38.Ft size_t 39.Fn wcstombs "char * restrict s" "const wchar_t * restrict pwcs" "size_t n" 40.\" ---------------------------------------------------------------------- 41.Sh DESCRIPTION 42.Fn wcstombs 43converts the null-terminated wide-character string pointed to by 44.Fa pwcs 45to the corresponding multibyte character string, 46and stores up to 47.Fa n 48bytes in the array pointed to by 49.Fa s . 50Each character will be converted as if 51.Xr wctomb 3 52is continuously called, except the internal state of 53.Xr wctomb 3 54will not be affected. 55.Pp 56For state-dependent encoding, the 57.Fn wcstombs 58implies the result multibyte character string pointed to by 59.Fa s 60always to begin with an initial state. 61.Pp 62The behaviour of the 63.Fn wcstombs 64is affected by the 65.Dv LC_CTYPE 66category of the current locale. 67.Pp 68There are special cases: 69.Bl -tag -width 012345678901 70.It s == NULL 71The 72.Fn wcstombs 73function returns the number of bytes to store the whole multibyte 74character string corresponding to the wide-character string pointed to by 75.Fa pwcs . 76In this case, 77.Fa n 78is ignored. 79.It pwcs == NULL 80Undefined (may causes the program to crash). 81.El 82.\" ---------------------------------------------------------------------- 83.Sh RETURN VALUES 84.Fn wcstombs 85returns: 86.Bl -tag -width 012345678901 87.It 0 or positive 88Number of bytes stored in the array pointed to by 89.Fa s . 90There are no cases that the value returned is greater than 91.Fa n 92(unless 93.Fa s 94is a null pointer). 95If the return value is equal to 96.Fa n , 97the string pointed to by 98.Fa s 99will not be null-terminated. 100.It (size_t)-1 101.Fa pwcs 102points the string containing invalid wide character. 103.Fn wcstombs 104also sets 105.Va errno 106to indicate the error. 107.El 108.\" ---------------------------------------------------------------------- 109.Sh ERRORS 110.Fn wcstombs 111may cause an error in the following cases: 112.Bl -tag -width Er 113.It Bq Er EILSEQ 114.Fa pwcs 115Points to the string containing invalid wide character. 116.El 117.\" ---------------------------------------------------------------------- 118.Sh SEE ALSO 119.Xr setlocale 3 , 120.Xr wctomb 3 121.\" ---------------------------------------------------------------------- 122.Sh STANDARDS 123The 124.Fn wcstombs 125function conforms to 126.St -ansiC . 127The restrict qualifier is added at 128.\" .St -isoC99 . 129ISO/IEC 9899/1999 130.Pq Dq ISO C99 . 131