lib/libc/locale/mbstowcs.3

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