lib/libc/locale/wctomb.3

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