original/man3/mbstowcs.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 MBSTOWCS 3  2011-09-28 "GNU" "Linux Programmer's Manual"
  17 .SH NAME
  18 mbstowcs \- convert a multibyte string to a wide-character string
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <stdlib.h>
  22 .sp
  23 .BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n );
  24 .fi
  25 .SH DESCRIPTION
  26 If
  27 .I dest
  28 is not a NULL pointer,
  29 the
  30 .BR mbstowcs ()
  31 function converts the
  32 multibyte string
  33 .I src
  34 to a wide-character string starting at
  35 .IR dest .
  36 At most
  37 .I n
  38 wide characters are written to
  39 .IR dest .
  40 The conversion starts
  41 in the initial state.
  42 The conversion can stop for three reasons:
  43 .IP 1. 3
  44 An invalid multibyte sequence has been encountered.
  45 In this case
  46 .I (size_t)\ \-1
  47 is returned.
  48 .IP 2.
  49 .I n
  50 non-L\(aq\\0\(aq wide characters have been stored at
  51 .IR dest .
  52 In this
  53 case the number of wide characters written to
  54 .I dest
  55 is returned, but the
  56 shift state at this point is lost.
  57 .IP 3.
  58 The multibyte string has been completely converted, including the
  59 terminating null wide character (\(aq\\0\(aq).
  60 In this case the number of wide characters written to
  61 .IR dest ,
  62 excluding the terminating null wide character, is returned.
  63 .PP
  64 The programmer must ensure that there is room for at least
  65 .I n
  66 wide
  67 characters at
  68 .IR dest .
  69 .PP
  70 If
  71 .IR dest
  72 is NULL,
  73 .I n
  74 is ignored, and the conversion proceeds as
  75 above, except that the converted wide characters are not written out to memory,
  76 and that no length limit exists.
  77 .PP
  78 In order to avoid the case 2 above, the programmer should make sure
  79 .I n
  80 is
  81 greater or equal to
  82 .IR "mbstowcs(NULL,src,0)+1" .
  83 .SH RETURN VALUE
  84 The
  85 .BR mbstowcs ()
  86 function returns the number of wide characters that make
  87 up the converted part of the wide-character string, not including the
  88 terminating null wide character.
  89 If an invalid multibyte sequence was
  90 encountered,
  91 .I (size_t)\ \-1
  92 is returned.
  93 .SH CONFORMING TO
  94 C99.
  95 .SH NOTES
  96 The behavior of
  97 .BR mbstowcs ()
  98 depends on the
  99 .B LC_CTYPE
 100 category of the
 101 current locale.
 102 .PP
 103 The function
 104 .BR mbsrtowcs (3)
 105 provides a better interface to the same
 106 functionality.
 107 .SH SEE ALSO
 108 .BR mbsrtowcs (3),
 109 .BR wcstombs (3)