lib/libc/locale/wcstombs.3

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