original/man3/mbrtowc.3

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