lib/libc/locale/wctomb.3

   1 .\" $NetBSD: wctomb.3,v 1.5 2006/10/14 07:51:01 wiz 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 February 3, 2002
  28 .Dt WCTOMB 3
  29 .Os
  30 .Sh NAME
  31 .Nm wctomb
  32 .Nd converts a wide character to a multibyte character
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In stdlib.h
  37 .Ft int
  38 .Fn wctomb "char * s" "const wchar_t wchar"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn wctomb
  42 converts the wide character
  43 .Fa wchar
  44 to the corresponding multibyte character, and stores it in the array
  45 pointed to by
  46 .Fa s .
  47 .Fn wctomb
  48 may store at most
  49 .Dv MB_CUR_MAX
  50 bytes in the array.
  51 .Pp
  52 In state-dependent encoding,
  53 .Fn wctomb
  54 may store the special sequence to change the conversion state
  55 before an actual multibyte character into the array pointed to by
  56 .Fa s .
  57 If
  58 .Fa wchar
  59 is a nul wide character
  60 .Pq Sq \e0 ,
  61 this function sets its own internal state to an initial conversion state.
  62 .Pp
  63 Calling any other functions in
  64 .Lb libc
  65 never changes the internal state of
  66 .Fn wctomb ,
  67 except changing the
  68 .Dv LC_CTYPE
  69 category of the current locale by calling
  70 .Xr setlocale 3 .
  71 Such
  72 .Xr setlocale 3
  73 calls cause the internal state of this function to be indeterminate.
  74 .Pp
  75 The behaviour of
  76 .Fn wctomb
  77 is affected by the
  78 .Dv LC_CTYPE
  79 category of the current locale.
  80 .Pp
  81 There is one special case:
  82 .Bl -tag -width 012345678901
  83 .It s == NULL
  84 .Fn wctomb
  85 initializes its own internal state to an initial state, and
  86 determines whether the current encoding is state-dependent.
  87 This function returns 0 if the encoding is state-independent,
  88 otherwise non-zero.
  89 In this case,
  90 .Fa wchar
  91 is completely ignored.
  92 .El
  93 .Sh RETURN VALUES
  94 Normally,
  95 .Fn wctomb
  96 returns:
  97 .Bl -tag -width 012345678901
  98 .It positive
  99 Number of bytes for the valid multibyte character pointed to by
 100 .Fa s .
 101 There are no cases that the value returned is greater than
 102 .Fa n
 103 or the value of the
 104 .Dv MB_CUR_MAX
 105 macro.
 106 .It -1
 107 .Fa wchar
 108 is an invalid wide character.
 109 .El
 110 .Pp
 111 If
 112 .Fa s
 113 is equal to
 114 .Dv NULL ,
 115 .Fn mbtowc
 116 returns:
 117 .Bl -tag -width 0123456789
 118 .It 0
 119 The current encoding is state-independent.
 120 .It non-zero
 121 The current encoding is state-dependent.
 122 .El
 123 .Sh ERRORS
 124 No errors are defined.
 125 .Sh SEE ALSO
 126 .Xr setlocale 3
 127 .Sh STANDARDS
 128 The
 129 .Fn wctomb
 130 function conforms to
 131 .St -ansiC .