locale/FreeBSD/wcsrtombs.3

   1 .\" Copyright (c) 2002-2004 Tim J. Robbins
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libc/locale/wcsrtombs.3,v 1.5 2004/07/21 10:54:57 tjr Exp $
  26 .\"
  27 .Dd July 21, 2004
  28 .Dt WCSRTOMBS 3
  29 .Os
  30 .Sh NAME
  31 .Nm wcsnrtombs ,
  32 .Nm wcsnrtombs_l ,
  33 .Nm wcsrtombs ,
  34 .Nm wcsrtombs_l
  35 .Nd "convert a wide-character string to a character string (restartable)"
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In wchar.h
  40 .Ft size_t
  41 .Fo wcsnrtombs
  42 .Fa "char *restrict dst"
  43 .Fa "const wchar_t **restrict src"
  44 .Fa "size_t nwc"
  45 .Fa "size_t len"
  46 .Fa "mbstate_t *restrict ps"
  47 .Fc
  48 .Ft size_t
  49 .Fo wcsrtombs
  50 .Fa "char *restrict dst"
  51 .Fa "const wchar_t **restrict src"
  52 .Fa "size_t len"
  53 .Fa "mbstate_t *restrict ps"
  54 .Fc
  55 .In wchar.h
  56 .In xlocale.h
  57 .Ft size_t
  58 .Fo wcsnrtombs_l
  59 .Fa "char *restrict dst"
  60 .Fa "const wchar_t **restrict src"
  61 .Fa "size_t nwc"
  62 .Fa "size_t len"
  63 .Fa "mbstate_t *restrict ps"
  64 .Fa "locale_t loc"
  65 .Fc
  66 .Ft size_t
  67 .Fo wcsrtombs_l
  68 .Fa "char *restrict dst"
  69 .Fa "const wchar_t **restrict src"
  70 .Fa "size_t len"
  71 .Fa "mbstate_t *restrict ps"
  72 .Fa "locale_t loc"
  73 .Fc
  74 .Sh DESCRIPTION
  75 The
  76 .Fn wcsrtombs
  77 function converts a string of wide characters,
  78 indirectly pointed to by
  79 .Fa src ,
  80 to a corresponding multi-byte character string,
  81 stored in the array pointed to by
  82 .Fa dst .
  83 No more than
  84 .Fa len
  85 bytes are written to
  86 .Fa dst .
  87 .Pp
  88 If
  89 .Fa dst
  90 is
  91 .Dv NULL ,
  92 no characters are stored.
  93 .Pp
  94 If
  95 .Fa dst
  96 is not
  97 .Dv NULL ,
  98 the pointer pointed to by
  99 .Fa src
 100 is updated to point to the character after the one that conversion stopped at.
 101 If conversion stops because a null character is encountered,
 102 .Fa *src
 103 is set to
 104 .Dv NULL .
 105 .Pp
 106 The
 107 .Vt mbstate_t
 108 argument,
 109 .Fa ps ,
 110 is used to keep track of the shift state.
 111 If it is
 112 .Dv NULL ,
 113 .Fn wcsrtombs
 114 uses an internal, static
 115 .Vt mbstate_t
 116 object, which is initialized to the initial conversion state
 117 at program startup.
 118 .Pp
 119 The
 120 .Fn wcsnrtombs
 121 function behaves identically to
 122 .Fn wcsrtombs ,
 123 except that conversion stops after reading at most
 124 .Fa nwc
 125 characters from the buffer pointed to by
 126 .Fa src .
 127 .Pp
 128 Although the
 129 .Fn wcsrtombs
 130 and
 131 .Fn wcsnrtombs
 132 functions use the current locale, the
 133 .Fn wcsrtombs_l
 134 and
 135 .Fn wcsnrtombs_l
 136 functions may be passed locales directly. See
 137 .Xr xlocale 3
 138 for more information.
 139 .Sh RETURN VALUES
 140 If successful, the
 141 .Fn wcsrtombs
 142 and
 143 .Fn wcsnrtombs
 144 functions return the number of bytes stored in
 145 the array pointed to by
 146 .Fa dst
 147 (not including any terminating null);
 148 otherwise, they return
 149 .Po Vt size_t Pc Ns \-1 .
 150 .Sh ERRORS
 151 The
 152 .Fn wcsrtombs
 153 and
 154 .Fn wcsnrtombs
 155 functions will fail if:
 156 .Bl -tag -width Er
 157 .It Bq Er EILSEQ
 158 An invalid wide character was encountered.
 159 .It Bq Er EINVAL
 160 The conversion state is invalid.
 161 .El
 162 .Sh SEE ALSO
 163 .Xr mbsrtowcs 3 ,
 164 .Xr wcrtomb 3 ,
 165 .Xr wcstombs 3 ,
 166 .Xr xlocale 3
 167 .Sh STANDARDS
 168 The
 169 .Fn wcsrtombs
 170 function conforms to
 171 .St -isoC-99 .
 172 .Pp
 173 The
 174 .Fn wcsnrtombs
 175 function is an extension to the standard.