original/man3/wcsnrtombs.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" References consulted:
  11 .\"   GNU glibc-2 source code and manual
  12 .\"   Dinkumware C library reference http://www.dinkumware.com/
  13 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  14 .\"
  15 .TH WCSNRTOMBS 3  2014-03-18 "GNU" "Linux Programmer's Manual"
  16 .SH NAME
  17 wcsnrtombs \- convert a wide-character string to a multibyte string
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <wchar.h>
  21 .sp
  22 .BI "size_t wcsnrtombs(char *" dest ", const wchar_t **" src ", size_t " nwc ,
  23 .BI "                  size_t " len ", mbstate_t *" ps );
  24 .fi
  25 .sp
  26 .in -4n
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .in
  30 .sp
  31 .BR wcsnrtombs ():
  32 .PD 0
  33 .ad l
  34 .RS 4
  35 .TP 4
  36 Since glibc 2.10:
  37 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  38 .TP
  39 Before glibc 2.10:
  40 _GNU_SOURCE
  41 .RE
  42 .ad
  43 .PD
  44 .SH DESCRIPTION
  45 The
  46 .BR wcsnrtombs ()
  47 function is like the
  48 .BR wcsrtombs (3)
  49 function,
  50 except that the number of wide characters to be converted,
  51 starting at
  52 .IR *src ,
  53 is limited to
  54 .IR nwc .
  55 .PP
  56 If
  57 .I dest
  58 is not NULL,
  59 the
  60 .BR wcsnrtombs ()
  61 function converts
  62 at most
  63 .I nwc
  64 wide characters from
  65 the wide-character string
  66 .I *src
  67 to a multibyte string starting at
  68 .IR dest .
  69 At most
  70 .I len
  71 bytes are written to
  72 .IR dest .
  73 The shift state
  74 .I *ps
  75 is updated.
  76 The conversion is effectively performed by repeatedly
  77 calling
  78 .IR "wcrtomb(dest, *src, ps)" ,
  79 as long as this call succeeds,
  80 and then incrementing
  81 .I dest
  82 by the
  83 number of bytes written and
  84 .I *src
  85 by one.
  86 The conversion can stop for three reasons:
  87 .IP 1. 3
  88 A wide character has been encountered that can not be represented as a
  89 multibyte sequence (according to the current locale).
  90 In this case,
  91 .I *src
  92 is left pointing to the invalid wide character,
  93 .I (size_t)\ \-1
  94 is returned,
  95 and
  96 .I errno
  97 is set to
  98 .BR EILSEQ .
  99 .IP 2.
 100 .I nwc
 101 wide characters have been
 102 converted without encountering a null wide character (L\(aq\\0\(aq),
 103 or the length limit forces a stop.
 104 In this case,
 105 .I *src
 106 is left pointing
 107 to the next wide character to be converted, and the number of bytes written
 108 to
 109 .I dest
 110 is returned.
 111 .IP 3.
 112 The wide-character string has been completely converted, including the
 113 terminating null wide character (which has the side effect of bringing back
 114 .I *ps
 115 to the initial state).
 116 In this case,
 117 .I *src
 118 is set to NULL, and the number
 119 of bytes written to
 120 .IR dest ,
 121 excluding the terminating null byte (\(aq\\0\(aq), is
 122 returned.
 123 .PP
 124 If
 125 .IR dest
 126 is NULL,
 127 .I len
 128 is ignored,
 129 and the conversion proceeds as above,
 130 except that the converted bytes are not written out to memory, and that
 131 no destination length limit exists.
 132 .PP
 133 In both of the above cases,
 134 if
 135 .I ps
 136 is NULL, a static anonymous
 137 state known only to the
 138 .BR wcsnrtombs ()
 139 function is used instead.
 140 .PP
 141 The programmer must ensure that there is room for at least
 142 .I len
 143 bytes
 144 at
 145 .IR dest .
 146 .SH RETURN VALUE
 147 The
 148 .BR wcsnrtombs ()
 149 function returns
 150 the number of bytes that make up the
 151 converted part of multibyte sequence,
 152 not including the terminating null byte.
 153 If a wide character was encountered which
 154 could not be converted,
 155 .I (size_t)\ \-1
 156 is returned, and
 157 .I errno
 158 set to
 159 .BR EILSEQ .
 160 .SH CONFORMING TO
 161 POSIX.1-2008.
 162 .SH NOTES
 163 The behavior of
 164 .BR wcsnrtombs ()
 165 depends on the
 166 .B LC_CTYPE
 167 category of the
 168 current locale.
 169 .PP
 170 Passing NULL as
 171 .I ps
 172 is not multithread safe.
 173 .SH SEE ALSO
 174 .BR iconv (3),
 175 .BR mbsinit (3),
 176 .BR wcsrtombs (3)
 177 .SH COLOPHON
 178 This page is part of release 3.79 of the Linux
 179 .I man-pages
 180 project.
 181 A description of the project,
 182 information about reporting bugs,
 183 and the latest version of this page,
 184 can be found at
 185 \%http://www.kernel.org/doc/man\-pages/.