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  2011-09-28 "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
  71 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 CONFORMING TO
 115 C99.
 116 .SH NOTES
 117 The behavior of
 118 .BR mbtowc ()
 119 depends on the
 120 .B LC_CTYPE
 121 category of the
 122 current locale.
 123 .PP
 124 This function is not multithread safe.
 125 The function
 126 .BR mbrtowc (3)
 127 provides
 128 a better interface to the same functionality.
 129 .SH SEE ALSO
 130 .BR MB_CUR_MAX (3),
 131 .BR mbrtowc (3),
 132 .BR mbstowcs (3)