man3/mbtowc.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 MBTOWC 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  17 .SH NAME
  18 mbtowc \- convert a multibyte sequence to a wide character
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <stdlib.h>
  22 .PP
  23 .BI "int mbtowc(wchar_t *restrict " pwc ", const char *restrict " s \
  24 ", size_t " n );
  25 .fi
  26 .SH DESCRIPTION
  27 The main case for this function is when
  28 .IR s
  29 is not NULL and
  30 .I pwc
  31 is
  32 not NULL.
  33 In this case, the
  34 .BR mbtowc ()
  35 function inspects at most
  36 .I n
  37 bytes of the multibyte string starting at
  38 .IR s ,
  39 extracts the next complete
  40 multibyte character, converts it to a wide character and stores it at
  41 .IR *pwc .
  42 It updates an internal shift state known only to the
  43 .BR mbtowc ()
  44 function.
  45 If
  46 .I s
  47 does not point to a null byte (\(aq\e0\(aq), it returns the number
  48 of bytes that were consumed from
  49 .IR s ,
  50 otherwise it returns 0.
  51 .PP
  52 If the
  53 .IR n
  54 bytes starting at
  55 .I s
  56 do not contain a complete multibyte
  57 character, or if they contain an invalid multibyte sequence,
  58 .BR mbtowc ()
  59 returns \-1.
  60 This can happen even if
  61 .I n
  62 >=
  63 .IR MB_CUR_MAX ,
  64 if the multibyte string contains redundant shift sequences.
  65 .PP
  66 A different case is when
  67 .IR s
  68 is not NULL but
  69 .I pwc
  70 is NULL.
  71 In this case, the
  72 .BR mbtowc ()
  73 function behaves as above, except that it does not
  74 store the converted wide character in memory.
  75 .PP
  76 A third case is when
  77 .I s
  78 is NULL.
  79 In this case,
  80 .IR pwc
  81 and
  82 .I n
  83 are
  84 ignored.
  85 The
  86 .BR mbtowc ()
  87 function
  88 .\" The Dinkumware doc and the Single UNIX specification say this, but
  89 .\" glibc doesn't implement this.
  90 resets the shift state, only known to this function,
  91 to the initial state, and
  92 returns nonzero if the encoding has nontrivial shift state, or zero if the
  93 encoding is stateless.
  94 .SH RETURN VALUE
  95 If
  96 .I s
  97 is not NULL, the
  98 .BR mbtowc ()
  99 function returns the number of
 100 consumed bytes starting at
 101 .IR s ,
 102 or 0 if
 103 .I s
 104 points to a null byte,
 105 or \-1 upon failure.
 106 .PP
 107 If
 108 .I s
 109 is NULL, the
 110 .BR mbtowc ()
 111 function
 112 returns nonzero if the encoding
 113 has nontrivial shift state, or zero if the encoding is stateless.
 114 .SH ATTRIBUTES
 115 For an explanation of the terms used in this section, see
 116 .BR attributes (7).
 117 .ad l
 118 .nh
 119 .TS
 120 allbox;
 121 lbx lb lb
 122 l l l.
 123 Interface       Attribute       Value
 124 T{
 125 .BR mbtowc ()
 126 T}      Thread safety   MT-Unsafe race
 127 .TE
 128 .hy
 129 .ad
 130 .sp 1
 131 .SH CONFORMING TO
 132 POSIX.1-2001, POSIX.1-2008, C99.
 133 .SH NOTES
 134 The behavior of
 135 .BR mbtowc ()
 136 depends on the
 137 .B LC_CTYPE
 138 category of the
 139 current locale.
 140 .PP
 141 This function is not multithread safe.
 142 The function
 143 .BR mbrtowc (3)
 144 provides
 145 a better interface to the same functionality.
 146 .SH SEE ALSO
 147 .BR MB_CUR_MAX (3),
 148 .BR mblen (3),
 149 .BR mbrtowc (3),
 150 .BR mbstowcs (3),
 151 .BR wcstombs (3),
 152 .BR wctomb (3)