original/man3/mbsrtowcs.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" References consulted:
  11 .\"   GNU glibc-2 source code and manual
  12 .\"   Dinkumware C library reference http://www.dinkumware.com/
  13 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  14 .\"   ISO/IEC 9899:1999
  15 .\"
  16 .TH MBSRTOWCS 3  2014-03-18 "GNU" "Linux Programmer's Manual"
  17 .SH NAME
  18 mbsrtowcs \- convert a multibyte string to a wide-character string
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <wchar.h>
  22 .sp
  23 .BI "size_t mbsrtowcs(wchar_t *" dest ", const char **" src ,
  24 .BI "                  size_t " len ", mbstate_t *" ps );
  25 .fi
  26 .SH DESCRIPTION
  27 If
  28 .I dest
  29 is not NULL, the
  30 .BR mbsrtowcs ()
  31 function converts the
  32 multibyte string
  33 .I *src
  34 to a wide-character string starting at
  35 .IR dest .
  36 At most
  37 .I len
  38 wide characters are written to
  39 .IR dest .
  40 The shift state
  41 .I *ps
  42 is updated.
  43 The conversion is effectively performed by repeatedly
  44 calling
  45 .I "mbrtowc(dest, *src, n, ps)"
  46 where
  47 .I n
  48 is some
  49 positive number, as long as this call succeeds, and then incrementing
  50 .I dest
  51 by one and
  52 .I *src
  53 by the number of bytes consumed.
  54 The conversion can stop for three reasons:
  55 .IP 1. 3
  56 An invalid multibyte sequence has been encountered.
  57 In this case
  58 .I *src
  59 is left pointing to the invalid multibyte sequence,
  60 .I (size_t)\ \-1
  61 is returned,
  62 and
  63 .I errno
  64 is set to
  65 .BR EILSEQ .
  66 .IP 2.
  67 .I len
  68 non-L\(aq\\0\(aq wide characters have been stored at
  69 .IR dest .
  70 In this
  71 case
  72 .I *src
  73 is left pointing to the next
  74 multibyte sequence to be converted,
  75 and the number of wide characters written to
  76 .I dest
  77 is returned.
  78 .IP 3.
  79 The multibyte string has been completely converted, including the
  80 terminating null wide character (\(aq\\0\(aq), which has the side
  81 effect of bringing back
  82 .I *ps
  83 to the
  84 initial state.
  85 In this case
  86 .I *src
  87 is set to NULL, and the number of wide
  88 characters written to
  89 .IR dest ,
  90 excluding the terminating null wide character, is returned.
  91 .PP
  92 If
  93 .IR dest
  94 is NULL,
  95 .I len
  96 is ignored,
  97 and the conversion proceeds as above,
  98 except that the converted wide characters are not written out to memory,
  99 and that no length limit exists.
 100 .PP
 101 In both of the above cases,
 102 if
 103 .I ps
 104 is NULL, a static anonymous
 105 state known only to the
 106 .BR mbsrtowcs ()
 107 function is used instead.
 108 .PP
 109 The programmer must ensure that there is room for at least
 110 .I len
 111 wide
 112 characters at
 113 .IR dest .
 114 .SH RETURN VALUE
 115 The
 116 .BR mbsrtowcs ()
 117 function returns the number of wide characters that make
 118 up the converted part of the wide-character string, not including the
 119 terminating null wide character.
 120 If an invalid multibyte sequence was
 121 encountered,
 122 .I (size_t)\ \-1
 123 is returned, and
 124 .I errno
 125 set to
 126 .BR EILSEQ .
 127 .SH CONFORMING TO
 128 C99.
 129 .SH NOTES
 130 The behavior of
 131 .BR mbsrtowcs ()
 132 depends on the
 133 .B LC_CTYPE
 134 category of the
 135 current locale.
 136 .PP
 137 Passing NULL as
 138 .I ps
 139 is not multithread safe.
 140 .SH SEE ALSO
 141 .BR iconv (3),
 142 .BR mbrtowc (3),
 143 .BR mbsinit (3),
 144 .BR mbsnrtowcs (3),
 145 .BR mbstowcs (3)