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  2014-03-18 "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 .sp
  23 .BI "int mbtowc(wchar_t *" pwc ", const char *" s ", size_t " n );
  24 .fi
  25 .SH DESCRIPTION
  26 The main case for this function is when
  27 .IR 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\\0\(aq), it returns the number
  47 of bytes that were consumed from
  48 .IR s ,
  49 otherwise it returns 0.
  50 .PP
  51 If the
  52 .IR 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 .PP
  65 A different case is when
  66 .IR 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 .PP
  75 A third case is when
  76 .I s
  77 is NULL.
  78 In this case,
  79 .IR 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 .PP
 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 CONFORMING TO
 114 C99.
 115 .SH NOTES
 116 The behavior of
 117 .BR mbtowc ()
 118 depends on the
 119 .B LC_CTYPE
 120 category of the
 121 current locale.
 122 .PP
 123 This function is not multithread safe.
 124 The function
 125 .BR mbrtowc (3)
 126 provides
 127 a better interface to the same functionality.
 128 .SH SEE ALSO
 129 .BR MB_CUR_MAX (3),
 130 .BR mblen (3),
 131 .BR mbrtowc (3),
 132 .BR mbstowcs (3),
 133 .BR wctomb (3),
 134 .BR wcstombs (3)