man3/mbtowc.3

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