lib/libc/locale/mbstowcs.3

   1 .\" $NetBSD: mbstowcs.3,v 1.12 2011/03/16 09:32:12 mbalmer Exp $
   2 .\"
   3 .\" Copyright (c)2002 Citrus Project,
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd March 16, 2011
  28 .Dt MBSTOWCS 3
  29 .Os
  30 .\" ----------------------------------------------------------------------
  31 .Sh NAME
  32 .Nm mbstowcs
  33 .Nd converts a multibyte character string to a wide-character string
  34 .\" ----------------------------------------------------------------------
  35 .Sh LIBRARY
  36 .Lb libc
  37 .\" ----------------------------------------------------------------------
  38 .Sh SYNOPSIS
  39 .In stdlib.h
  40 .Ft size_t
  41 .Fn mbstowcs "wchar_t * restrict pwcs" "const char * restrict s" "size_t n"
  42 .\" ----------------------------------------------------------------------
  43 .Sh DESCRIPTION
  44 .Fn mbstowcs
  45 converts a nul-terminated multibyte character string pointed to by
  46 .Fa s
  47 to the corresponding wide-character string and stores it in the array
  48 pointed to by
  49 .Fa pwcs .
  50 This function may modify the first at most
  51 .Fa n
  52 elements of the array pointed to by
  53 .Fa pwcs .
  54 Each character will be converted as if
  55 .Xr mbtowc 3
  56 is continuously called, except the internal state of
  57 .Xr mbtowc 3
  58 will not be affected.
  59 .Pp
  60 For state-dependent encoding,
  61 .Fn mbstowcs
  62 implies the multibyte character string pointed to by
  63 .Fa s
  64 always begins with an initial state.
  65 .Pp
  66 These are the special cases:
  67 .Bl -tag -width 012345678901
  68 .It pwcs == NULL
  69 .Fn mbstowcs
  70 returns the number of elements to store the whole wide-character string
  71 corresponding to the multibyte character string pointed to by
  72 .Fa s .
  73 In this case,
  74 .Fa n
  75 is ignored.
  76 .It s == NULL
  77 Undefined (may cause the program to crash).
  78 .El
  79 .\" ----------------------------------------------------------------------
  80 .Sh RETURN VALUES
  81 .Fn mbstowcs
  82 returns:
  83 .Bl -tag -width 012345678901
  84 .It 0 or positive
  85 Number of elements stored in the array pointed to by
  86 .Fa pwcs .
  87 There are no cases that the value returned is greater than
  88 .Fa n
  89 (unless
  90 .Fa pwcs
  91 is a null pointer) or the value of the
  92 .Dv MB_CUR_MAX
  93 macro.
  94 If the return value is equal to
  95 .Fa n ,
  96 the string pointed to by
  97 .Fa pwcs
  98 will not be nul-terminated.
  99 .It (size_t)-1
 100 .Fa s
 101 points to a string containing an invalid or incomplete multibyte character.
 102 The
 103 .Fn mbstowcs
 104 also sets
 105 .Va errno
 106 to indicate the error.
 107 .El
 108 .\" ----------------------------------------------------------------------
 109 .Sh ERRORS
 110 .Fn mbstowcs
 111 may cause an error in the following case:
 112 .Bl -tag -width Er
 113 .It Bq Er EILSEQ
 114 .Fa s
 115 points to a string containing an invalid or incomplete multibyte character.
 116 .El
 117 .\" ----------------------------------------------------------------------
 118 .Sh SEE ALSO
 119 .Xr mbtowc 3 ,
 120 .Xr setlocale 3 ,
 121 .Xr wcstombs 3
 122 .\" ----------------------------------------------------------------------
 123 .Sh STANDARDS
 124 The
 125 .Fn mbstowcs
 126 function conforms to
 127 .St -ansiC .
 128 The restrict qualifier is added at
 129 .St -isoC-99 .