man3/mbrtowc.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
  14 .\"      http://www.UNIX-systems.org/online.html
  15 .\"   ISO/IEC 9899:1999
  16 .\"
  17 .TH MBRTOWC 3  2015-08-08 "GNU" "Linux Programmer's Manual"
  18 .SH NAME
  19 mbrtowc \- convert a multibyte sequence to a wide character
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <wchar.h>
  23 .PP
  24 .BI "size_t mbrtowc(wchar_t *" pwc ", const char *" s ", size_t " n \
  25 ", mbstate_t *" ps );
  26 .fi
  27 .SH DESCRIPTION
  28 The main case for this function is when
  29 .IR s
  30 is not NULL and
  31 .I pwc
  32 is
  33 not NULL.
  34 In this case, the
  35 .BR mbrtowc ()
  36 function inspects at most
  37 .I n
  38 bytes of the multibyte string starting at
  39 .IR s ,
  40 extracts the next complete
  41 multibyte character, converts it to a wide character and stores it at
  42 .IR *pwc .
  43 It updates the shift state
  44 .IR *ps .
  45 If the converted wide
  46 character is not L\(aq\\0\(aq (the null wide character),
  47 it returns the number of bytes that were consumed
  48 from
  49 .IR s .
  50 If the converted wide character is L\(aq\\0\(aq, it resets the shift
  51 state
  52 .I *ps
  53 to the initial state and returns 0.
  54 .PP
  55 If the
  56 .IR n
  57 bytes starting at
  58 .I s
  59 do not contain a complete multibyte
  60 character,
  61 .BR mbrtowc ()
  62 returns
  63 .IR "(size_t)\ \-2" .
  64 This can happen even if
  65 .I n
  66 >=
  67 .IR MB_CUR_MAX ,
  68 if the multibyte string contains redundant shift
  69 sequences.
  70 .PP
  71 If the multibyte string starting at
  72 .I s
  73 contains an invalid multibyte
  74 sequence before the next complete character,
  75 .BR mbrtowc ()
  76 returns
  77 .IR "(size_t)\ \-1"
  78 and sets
  79 .I errno
  80 to
  81 .BR EILSEQ .
  82 In this case,
  83 the effects on
  84 .I *ps
  85 are undefined.
  86 .PP
  87 A different case is when
  88 .IR s
  89 is not NULL but
  90 .I pwc
  91 is NULL.
  92 In this case, the
  93 .BR mbrtowc ()
  94 function behaves as above, except that it does not
  95 store the converted wide character in memory.
  96 .PP
  97 A third case is when
  98 .I s
  99 is NULL.
 100 In this case,
 101 .IR pwc
 102 and
 103 .I n
 104 are
 105 ignored.
 106 If the conversion state represented by
 107 .I *ps
 108 denotes an
 109 incomplete multibyte character conversion, the
 110 .BR mbrtowc ()
 111 function
 112 returns
 113 .IR "(size_t)\ \-1" ,
 114 sets
 115 .I errno
 116 to
 117 .BR EILSEQ ,
 118 and
 119 leaves
 120 .I *ps
 121 in an undefined state.
 122 Otherwise, the
 123 .BR mbrtowc ()
 124 function
 125 puts
 126 .I *ps
 127 in the initial state and returns 0.
 128 .PP
 129 In all of the above cases, if
 130 .I ps
 131 is NULL, a static anonymous
 132 state known only to the
 133 .BR mbrtowc ()
 134 function is used instead.
 135 Otherwise,
 136 .IR *ps
 137 must be a valid
 138 .I mbstate_t
 139 object.
 140 An
 141 .IR mbstate_t
 142 object
 143 .I a
 144 can be initialized to the initial state
 145 by zeroing it, for example using
 146 .PP
 147 .in +4n
 148 .EX
 149 memset(&a, 0, sizeof(a));
 150 .EE
 151 .in
 152 .SH RETURN VALUE
 153 The
 154 .BR mbrtowc ()
 155 function returns the number of bytes parsed from the
 156 multibyte sequence starting at
 157 .IR s ,
 158 if a non-L\(aq\\0\(aq wide character
 159 was recognized.
 160 It returns 0, if a L\(aq\\0\(aq wide character was recognized.
 161 It returns
 162 .I (size_t)\ \-1
 163 and sets
 164 .I errno
 165 to
 166 .BR EILSEQ ,
 167 if an invalid multibyte sequence was
 168 encountered.
 169 It returns
 170 .I "(size_t)\ \-2"
 171 if it couldn't parse a complete multibyte
 172 character, meaning that
 173 .I n
 174 should be increased.
 175 .SH ATTRIBUTES
 176 For an explanation of the terms used in this section, see
 177 .BR attributes (7).
 178 .TS
 179 allbox;
 180 lb lb lb
 181 l l l.
 182 Interface       Attribute       Value
 183 T{
 184 .BR mbrtowc ()
 185 T}      Thread safety   MT-Unsafe race:mbrtowc/!ps
 186 .TE
 187 .SH CONFORMING TO
 188 POSIX.1-2001, POSIX.1-2008, C99.
 189 .SH NOTES
 190 The behavior of
 191 .BR mbrtowc ()
 192 depends on the
 193 .B LC_CTYPE
 194 category of the
 195 current locale.
 196 .SH SEE ALSO
 197 .BR mbsinit (3),
 198 .BR mbsrtowcs (3)