original/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  2014-03-18 "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 .sp
  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 .sp
 147 .in +4n
 148 memset(&a, 0, sizeof(a));
 149 .in
 150 .SH RETURN VALUE
 151 The
 152 .BR mbrtowc ()
 153 function returns the number of bytes parsed from the
 154 multibyte sequence starting at
 155 .IR s ,
 156 if a non-L\(aq\\0\(aq wide character
 157 was recognized.
 158 It returns 0, if a L\(aq\\0\(aq wide character was recognized.
 159 It returns
 160 .I (size_t)\ \-1
 161 and sets
 162 .I errno
 163 to
 164 .BR EILSEQ ,
 165 if an invalid multibyte sequence was
 166 encountered.
 167 It returns
 168 .I "(size_t)\ \-2"
 169 if it couldn't parse a complete multibyte
 170 character, meaning that
 171 .I n
 172 should be increased.
 173 .SH ATTRIBUTES
 174 .SS Multithreading (see pthreads(7))
 175 The
 176 .BR mbrtowc ()
 177 function is thread-safe with exceptions.
 178 It is not thread-safe if called with a NULL \fIps\fP parameter.
 179 .SH CONFORMING TO
 180 C99.
 181 .SH NOTES
 182 The behavior of
 183 .BR mbrtowc ()
 184 depends on the
 185 .B LC_CTYPE
 186 category of the
 187 current locale.
 188 .SH SEE ALSO
 189 .BR mbsinit (3),
 190 .BR mbsrtowcs (3)
 191 .SH COLOPHON
 192 This page is part of release 3.79 of the Linux
 193 .I man-pages
 194 project.
 195 A description of the project,
 196 information about reporting bugs,
 197 and the latest version of this page,
 198 can be found at
 199 \%http://www.kernel.org/doc/man\-pages/.