original/man3/mbsnrtowcs.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 MBSNRTOWCS 3  2014-03-18 "GNU" "Linux Programmer's Manual"
  16 .SH NAME
  17 mbsnrtowcs \- convert a multibyte string to a wide-character string
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <wchar.h>
  21 .sp
  22 .BI "size_t mbsnrtowcs(wchar_t *" dest ", const char **" src ,
  23 .BI "                  size_t " nms ", 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 mbsnrtowcs ():
  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 mbsnrtowcs ()
  47 function is like the
  48 .BR mbsrtowcs (3)
  49 function, except that
  50 the number of bytes to be converted, starting at
  51 .IR *src ,
  52 is limited to
  53 .IR nms .
  54 .PP
  55 If
  56 .I dest
  57 is not NULL, the
  58 .BR mbsnrtowcs ()
  59 function converts at
  60 most
  61 .I nms
  62 bytes from the
  63 multibyte string
  64 .I *src
  65 to a wide-character string starting at
  66 .IR dest .
  67 At most
  68 .I len
  69 wide characters are written to
  70 .IR dest .
  71 The shift state
  72 .I *ps
  73 is updated.
  74 The conversion is effectively performed by repeatedly
  75 calling
  76 .I "mbrtowc(dest, *src, n, ps)"
  77 where
  78 .I n
  79 is some
  80 positive number, as long as this call succeeds, and then incrementing
  81 .I dest
  82 by one and
  83 .I *src
  84 by the number of bytes consumed.
  85 The
  86 conversion can stop for three reasons:
  87 .IP 1. 3
  88 An invalid multibyte sequence has been encountered.
  89 In this case,
  90 .I *src
  91 is left pointing to the invalid multibyte sequence,
  92 .I (size_t)\ \-1
  93 is returned,
  94 and
  95 .I errno
  96 is set to
  97 .BR EILSEQ .
  98 .IP 2.
  99 The
 100 .I nms
 101 limit forces a stop,
 102 or
 103 .I len
 104 non-L\(aq\\0\(aq wide characters
 105 have been stored at
 106 .IR dest .
 107 In this case,
 108 .I *src
 109 is left pointing to the
 110 next multibyte sequence to be converted, and the number of wide characters
 111 written to
 112 .I dest
 113 is returned.
 114 .IP 3.
 115 The multibyte string has been completely converted, including the
 116 terminating null wide character (\(aq\\0\(aq)
 117 (which has the side effect of bringing back
 118 .I *ps
 119 to the
 120 initial state).
 121 In this case,
 122 .I *src
 123 is set to NULL, and the number of wide
 124 characters written to
 125 .IR dest ,
 126 excluding the terminating null wide character,
 127 is returned.
 128 .PP
 129 If
 130 .IR dest
 131 is NULL,
 132 .I len
 133 is ignored, and the conversion proceeds as
 134 above, except that the converted wide characters
 135 are not written out to memory,
 136 and that no destination length limit exists.
 137 .PP
 138 In both of the above cases, if
 139 .I ps
 140 is NULL, a static anonymous
 141 state known only to the
 142 .BR mbsnrtowcs ()
 143 function is used instead.
 144 .PP
 145 The programmer must ensure that there is room for at least
 146 .I len
 147 wide
 148 characters at
 149 .IR dest .
 150 .SH RETURN VALUE
 151 The
 152 .BR mbsnrtowcs ()
 153 function returns the number of wide characters
 154 that make up the converted part of the wide-character string,
 155 not including the terminating null wide character.
 156 If an invalid multibyte sequence was
 157 encountered,
 158 .I (size_t)\ \-1
 159 is returned, and
 160 .I errno
 161 set to
 162 .BR EILSEQ .
 163 .SH CONFORMING TO
 164 POSIX.1-2008.
 165 .SH NOTES
 166 The behavior of
 167 .BR mbsnrtowcs ()
 168 depends on the
 169 .B LC_CTYPE
 170 category of the
 171 current locale.
 172 .PP
 173 Passing NULL as
 174 .I ps
 175 is not multithread safe.
 176 .SH SEE ALSO
 177 .BR iconv (3),
 178 .BR mbrtowc (3)
 179 .BR mbsinit (3),
 180 .BR mbsrtowcs (3)
 181 .SH COLOPHON
 182 This page is part of release 3.79 of the Linux
 183 .I man-pages
 184 project.
 185 A description of the project,
 186 information about reporting bugs,
 187 and the latest version of this page,
 188 can be found at
 189 \%http://www.kernel.org/doc/man\-pages/.