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