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 01:18:01 joerg Exp $
4 .\" Copyright (c)2002 Citrus Project,
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
31 .\" ----------------------------------------------------------------------
34 .Nd converts a wide character string to a multibyte character string
35 .\" ----------------------------------------------------------------------
38 .\" ----------------------------------------------------------------------
42 .Fn wcstombs "const char * restrict s" "wchar_t * restrict pwcs" "size_t n"
43 .\" ----------------------------------------------------------------------
46 converts the null-terminated wide character string pointed to by
48 to the corresponding multibyte character string,
49 and stores it in the array pointed to by
51 This function may modify the first at most
53 bytes of the array pointed to by
55 Each character will be converted as if
57 is continuously called, except the internal state of
61 For state-dependent encoding, the
63 implies the result multibyte character string pointed to by
65 always to begin with an initial state.
71 category of the current locale.
73 These are the special cases:
74 .Bl -tag -width 012345678901
78 returns the number of bytes to store the whole multibyte character string
79 corresponding to the wide character string pointed to by
85 Undefined (may cause the program to crash).
87 .\" ----------------------------------------------------------------------
91 .Bl -tag -width 012345678901
93 Number of bytes stored in the array pointed to by
95 There are no cases that the value returned is greater than
100 If the return value is equal to
102 the string pointed to by
104 will not be null-terminated.
107 points to a string containing an invalid wide character.
111 to indicate the error.
113 .\" ----------------------------------------------------------------------
116 may cause an error in the following case:
120 points to a string containing an invalid wide character.
122 .\" ----------------------------------------------------------------------
126 .\" ----------------------------------------------------------------------
132 The restrict qualifier is added at