1.\" Copyright (c) 2002-2004 Tim J. Robbins 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD: head/lib/libc/locale/mbsrtowcs.3 140081 2005-01-11 20:50:51Z ru $ 26.\" 27.Dd December 26, 2013 28.Dt MBSRTOWCS 3 29.Os 30.Sh NAME 31.Nm mbsrtowcs , 32.Nm mbsrtowcs_l , 33.Nm mbsnrtowcs , 34.Nm mbsnrtowcs_l 35.Nd "convert a character string to a wide-character string (restartable)" 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In wchar.h 40.Ft size_t 41.Fo mbsrtowcs 42.Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t len" 43.Fa "mbstate_t * restrict ps" 44.Fc 45.Ft size_t 46.Fo mbsnrtowcs 47.Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t nms" 48.Fa "size_t len" "mbstate_t * restrict ps" 49.Fc 50.In xlocale.h 51.Ft size_t 52.Fo mbsrtowcs_l 53.Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t len" 54.Fa "mbstate_t * restrict ps" "locale_t locale" 55.Fc 56.Ft size_t 57.Fo mbsnrtowcs_l 58.Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t nms" 59.Fa "size_t len" "mbstate_t * restrict ps" "locale_t locale" 60.Fc 61.Sh DESCRIPTION 62The 63.Fn mbsrtowcs 64and 65.Fn mbsrtowcs_l 66functions convert a sequence of multibyte characters pointed to indirectly by 67.Fa src 68into a sequence of corresponding wide characters and store at most 69.Fa len 70of them in the 71.Vt wchar_t 72array pointed to by 73.Fa dst , 74until they encounter a terminating null character 75.Pq Li '\e0' . 76.Pp 77If 78.Fa dst 79is 80.Dv NULL , 81no characters are stored. 82.Pp 83If 84.Fa dst 85is not 86.Dv NULL , 87the pointer pointed to by 88.Fa src 89is updated to point to the character after the one that conversion stopped at. 90If conversion stops because a null character is encountered, 91.Fa *src 92is set to 93.Dv NULL . 94.Pp 95The 96.Vt mbstate_t 97argument, 98.Fa ps , 99is used to keep track of the shift state. 100If it is 101.Dv NULL , 102.Fn mbsrtowcs 103and 104.Fn mbsrtowcs_l 105use an internal, static 106.Vt mbstate_t 107object, which is initialized to the initial conversion state 108at program startup. 109.Pp 110The 111.Fn mbsnrtowcs 112and 113.Fn mbsnrtowcs_l 114functions behave identically to 115.Fn mbsrtowcs 116and 117.Fn mbsrtowcs_l , 118except that conversion stops after reading at most 119.Fa nms 120bytes from the buffer pointed to by 121.Fa src . 122.Pp 123The 124.Fn mbsrtowcs_l 125and 126.Fn mbsnrtowcs_l 127functions take an explicit 128.Fa locale 129argument, whereas the 130.Fn mbsrtowcs 131and 132.Fn mbsnrtowcs 133functions use the current global or per-thread locale. 134.Sh RETURN VALUES 135The 136.Fn mbsrtowcs , 137.Fn mbsrtowcs_l , 138.Fn mbsnrtowcs , 139and 140.Fn mbsnrtowcs_l 141functions return the number of wide characters stored in 142the array pointed to by 143.Fa dst 144if successful, otherwise they return 145.Po Vt size_t Pc Ns \-1 . 146.Sh ERRORS 147The 148.Fn mbsrtowcs , 149.Fn mbsrtowcs_l , 150.Fn mbsnrtowcs , 151and 152.Fn mbsnrtowcs_l 153functions will fail if: 154.Bl -tag -width Er 155.It Bq Er EILSEQ 156An invalid multibyte character sequence was encountered. 157.It Bq Er EINVAL 158The conversion state is invalid. 159.El 160.Sh SEE ALSO 161.Xr mbrtowc 3 , 162.Xr mbstowcs 3 , 163.Xr multibyte 3 , 164.Xr wcsrtombs 3 , 165.Xr xlocale 3 166.Sh STANDARDS 167The 168.Fn mbsrtowcs 169function conforms to 170.St -isoC-99 . 171.Pp 172The 173.Fn mbsrtowcs_l , 174.Fn mbsnrtowcs , 175and 176.Fn mbsnrtowcs_l 177functions are an extension to the standard. 178