lib/libc/locale/wcstombs.3

   1 .\" $NetBSD: src/lib/libc/locale/wcstombs.3,v 1.7 2004/01/24 16:58:54 wiz Exp $
   2 .\" $DragonFly: src/lib/libc/locale/wcstombs.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 4, 2002
  29 .Dt WCSTOMBS 3
  30 .Os
  31 .\" ----------------------------------------------------------------------
  32 .Sh NAME
  33 .Nm wcstombs
  34 .Nd converts a wide character string to a multibyte character string
  35 .\" ----------------------------------------------------------------------
  36 .Sh LIBRARY
  37 .Lb libc
  38 .\" ----------------------------------------------------------------------
  39 .Sh SYNOPSIS
  40 .In stdlib.h
  41 .Ft size_t
  42 .Fn wcstombs "const char * restrict s" "wchar_t * restrict pwcs" "size_t n"
  43 .\" ----------------------------------------------------------------------
  44 .Sh DESCRIPTION
  45 .Fn wcstombs
  46 converts the null-terminated wide character string pointed to by
  47 .Fa pwcs
  48 to the corresponding multibyte character string,
  49 and stores it in the array pointed to by
  50 .Fa s .
  51 This function may modify the first at most
  52 .Fa n
  53 bytes of the array pointed to by
  54 .Fa s .
  55 Each character will be converted as if
  56 .Xr wctomb 3
  57 is continuously called, except the internal state of
  58 .Xr wctomb 3
  59 will not be affected.
  60 .Pp
  61 For state-dependent encoding, the
  62 .Fn wcstombs
  63 implies the result multibyte character string pointed to by
  64 .Fa s
  65 always to begin with an initial state.
  66 .Pp
  67 The behaviour of
  68 .Fn wcstombs
  69 is affected by the
  70 .Dv LC_CTYPE
  71 category of the current locale.
  72 .Pp
  73 These are the special cases:
  74 .Bl -tag -width 012345678901
  75 .It s == NULL
  76 The
  77 .Fn wcstombs
  78 returns the number of bytes to store the whole multibyte character string
  79 corresponding to the wide character string pointed to by
  80 .Fa pwcs .
  81 In this case,
  82 .Fa n
  83 is ignored.
  84 .It pwcs == NULL
  85 Undefined (may cause the program to crash).
  86 .El
  87 .\" ----------------------------------------------------------------------
  88 .Sh RETURN VALUES
  89 .Fn wcstombs
  90 returns:
  91 .Bl -tag -width 012345678901
  92 .It 0 or positive
  93 Number of bytes stored in the array pointed to by
  94 .Fa s .
  95 There are no cases that the value returned is greater than
  96 .Fa n
  97 (unless
  98 .Fa s
  99 is a null pointer).
 100 If the return value is equal to
 101 .Fa n ,
 102 the string pointed to by
 103 .Fa s
 104 will not be null-terminated.
 105 .It (size_t)-1
 106 .Fa pwcs
 107 points to a string containing an invalid wide character.
 108 .Fn wcstombs
 109 also sets
 110 .Va errno
 111 to indicate the error.
 112 .El
 113 .\" ----------------------------------------------------------------------
 114 .Sh ERRORS
 115 .Fn wcstombs
 116 may cause an error in the following case:
 117 .Bl -tag -width Er
 118 .It Bq Er EILSEQ
 119 .Fa pwcs
 120 points to a string containing an invalid wide character.
 121 .El
 122 .\" ----------------------------------------------------------------------
 123 .Sh SEE ALSO
 124 .Xr setlocale 3 ,
 125 .Xr wctomb 3
 126 .\" ----------------------------------------------------------------------
 127 .Sh STANDARDS
 128 The
 129 .Fn wcstombs
 130 function conforms to
 131 .St -ansiC .
 132 The restrict qualifier is added at
 133 .St -isoC-99 .