man3/mbtowc.3

   1 '\" t
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .\" References consulted:
   7 .\"   GNU glibc-2 source code and manual
   8 .\"   Dinkumware C library reference http://www.dinkumware.com/
   9 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  10 .\"   ISO/IEC 9899:1999
  11 .\"
  12 .TH mbtowc 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 mbtowc \- convert a multibyte sequence to a wide character
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <stdlib.h>
  21 .P
  22 .BI "int mbtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n "], \
  23 size_t " n );
  24 .fi
  25 .SH DESCRIPTION
  26 The main case for this function is when
  27 .I s
  28 is not NULL and
  29 .I pwc
  30 is
  31 not NULL.
  32 In this case, the
  33 .BR mbtowc ()
  34 function inspects at most
  35 .I n
  36 bytes of the multibyte string starting at
  37 .IR s ,
  38 extracts the next complete
  39 multibyte character, converts it to a wide character and stores it at
  40 .IR *pwc .
  41 It updates an internal shift state known only to the
  42 .BR mbtowc ()
  43 function.
  44 If
  45 .I s
  46 does not point to a null byte (\[aq]\e0\[aq]), it returns the number
  47 of bytes that were consumed from
  48 .IR s ,
  49 otherwise it returns 0.
  50 .P
  51 If the
  52 .I n
  53 bytes starting at
  54 .I s
  55 do not contain a complete multibyte
  56 character, or if they contain an invalid multibyte sequence,
  57 .BR mbtowc ()
  58 returns \-1.
  59 This can happen even if
  60 .I n
  61 >=
  62 .IR MB_CUR_MAX ,
  63 if the multibyte string contains redundant shift sequences.
  64 .P
  65 A different case is when
  66 .I s
  67 is not NULL but
  68 .I pwc
  69 is NULL.
  70 In this case, the
  71 .BR mbtowc ()
  72 function behaves as above, except that it does not
  73 store the converted wide character in memory.
  74 .P
  75 A third case is when
  76 .I s
  77 is NULL.
  78 In this case,
  79 .I pwc
  80 and
  81 .I n
  82 are
  83 ignored.
  84 The
  85 .BR mbtowc ()
  86 function
  87 .\" The Dinkumware doc and the Single UNIX specification say this, but
  88 .\" glibc doesn't implement this.
  89 resets the shift state, only known to this function,
  90 to the initial state, and
  91 returns nonzero if the encoding has nontrivial shift state, or zero if the
  92 encoding is stateless.
  93 .SH RETURN VALUE
  94 If
  95 .I s
  96 is not NULL, the
  97 .BR mbtowc ()
  98 function returns the number of
  99 consumed bytes starting at
 100 .IR s ,
 101 or 0 if
 102 .I s
 103 points to a null byte,
 104 or \-1 upon failure.
 105 .P
 106 If
 107 .I s
 108 is NULL, the
 109 .BR mbtowc ()
 110 function
 111 returns nonzero if the encoding
 112 has nontrivial shift state, or zero if the encoding is stateless.
 113 .SH ATTRIBUTES
 114 For an explanation of the terms used in this section, see
 115 .BR attributes (7).
 116 .TS
 117 allbox;
 118 lbx lb lb
 119 l l l.
 120 Interface       Attribute       Value
 121 T{
 122 .na
 123 .nh
 124 .BR mbtowc ()
 125 T}      Thread safety   MT-Unsafe race
 126 .TE
 127 .SH VERSIONS
 128 This function is not multithread safe.
 129 The function
 130 .BR mbrtowc (3)
 131 provides
 132 a better interface to the same functionality.
 133 .SH STANDARDS
 134 C11, POSIX.1-2008.
 135 .SH HISTORY
 136 POSIX.1-2001, C99.
 137 .SH NOTES
 138 The behavior of
 139 .BR mbtowc ()
 140 depends on the
 141 .B LC_CTYPE
 142 category of the
 143 current locale.
 144 .SH SEE ALSO
 145 .BR MB_CUR_MAX (3),
 146 .BR mblen (3),
 147 .BR mbrtowc (3),
 148 .BR mbstowcs (3),
 149 .BR wcstombs (3),
 150 .BR wctomb (3)