original/man3/mbrtowc.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
  14 .\"      http://www.UNIX-systems.org/online.html
  15 .\"   ISO/IEC 9899:1999
  16 .\"
  17 .TH MBRTOWC 3  2011-09-28 "GNU" "Linux Programmer's Manual"
  18 .SH NAME
  19 mbrtowc \- convert a multibyte sequence to a wide character
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <wchar.h>
  23 .sp
  24 .BI "size_t mbrtowc(wchar_t *" pwc ", const char *" s ", size_t " n \
  25 ", mbstate_t *" ps );
  26 .fi
  27 .SH DESCRIPTION
  28 The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is
  29 not NULL.
  30 In this case, the
  31 .BR mbrtowc ()
  32 function inspects at most \fIn\fP
  33 bytes of the multibyte string starting at \fIs\fP, extracts the next complete
  34 multibyte character, converts it to a wide character and stores it at
  35 \fI*pwc\fP.
  36 It updates the shift state \fI*ps\fP.
  37 If the converted wide
  38 character is not L\(aq\\0\(aq (the null wide character),
  39 it returns the number of bytes that were consumed
  40 from \fIs\fP.
  41 If the converted wide character is L\(aq\\0\(aq, it resets the shift
  42 state \fI*ps\fP to the initial state and returns 0.
  43 .PP
  44 If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte
  45 character,
  46 .BR mbrtowc ()
  47 returns \fI(size_t)\ \-2\fP.
  48 This can happen even if
  49 \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift
  50 sequences.
  51 .PP
  52 If the multibyte string starting at \fIs\fP contains an invalid multibyte
  53 sequence before the next complete character,
  54 .BR mbrtowc ()
  55 returns
  56 \fI(size_t)\ \-1\fP and sets \fIerrno\fP to \fBEILSEQ\fP.
  57 In this case,
  58 the effects on \fI*ps\fP are undefined.
  59 .PP
  60 A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL.
  61 In this
  62 case the
  63 .BR mbrtowc ()
  64 function behaves as above, except that it does not
  65 store the converted wide character in memory.
  66 .PP
  67 A third case is when \fIs\fP is NULL.
  68 In this case, \fIpwc\fP and \fIn\fP are
  69 ignored.
  70 If the conversion state represented by \fI*ps\fP denotes an
  71 incomplete multibyte character conversion, the
  72 .BR mbrtowc ()
  73 function
  74 returns \fI(size_t)\ \-1\fP, sets \fIerrno\fP to \fBEILSEQ\fP, and
  75 leaves \fI*ps\fP in an undefined state.
  76 Otherwise, the
  77 .BR mbrtowc ()
  78 function
  79 puts \fI*ps\fP in the initial state and returns 0.
  80 .PP
  81 In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous
  82 state only known to the mbrtowc function is used instead.
  83 Otherwise, \fI*ps\fP must be a valid \fImbstate_t\fP object.
  84 An \fImbstate_t\fP object \fIa\fP can be initialized to the initial state
  85 by zeroing it, for example using
  86 .sp
  87 .in +4n
  88 memset(&a, 0, sizeof(a));
  89 .in
  90 .SH RETURN VALUE
  91 The
  92 .BR mbrtowc ()
  93 function returns the number of bytes parsed from the
  94 multibyte sequence starting at \fIs\fP, if a non-L\(aq\\0\(aq wide character
  95 was recognized.
  96 It returns 0, if a L\(aq\\0\(aq wide character was recognized.
  97 It returns
  98 .I (size_t)\ \-1
  99 and sets \fIerrno\fP to \fBEILSEQ\fP, if an invalid multibyte sequence was
 100 encountered.
 101 It returns \fI(size_t)\ \-2\fP if it couldn't parse a complete multibyte
 102 character, meaning that \fIn\fP should be increased.
 103 .SH CONFORMING TO
 104 C99.
 105 .SH NOTES
 106 The behavior of
 107 .BR mbrtowc ()
 108 depends on the
 109 .B LC_CTYPE
 110 category of the
 111 current locale.
 112 .SH SEE ALSO
 113 .BR mbsrtowcs (3)