original/man3/mbstowcs.3

   1 '\" t -*- coding: UTF-8 -*-
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   3 .\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   6 .\" This is free documentation; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public License as
   8 .\" published by the Free Software Foundation; either version 2 of
   9 .\" the License, or (at your option) any later version.
  10 .\" %%%LICENSE_END
  11 .\"
  12 .\" References consulted:
  13 .\"   GNU glibc-2 source code and manual
  14 .\"   Dinkumware C library reference http://www.dinkumware.com/
  15 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  16 .\"   ISO/IEC 9899:1999
  17 .\"
  18 .TH MBSTOWCS 3  2014-03-18 "GNU" "Linux Programmer's Manual"
  19 .SH NAME
  20 mbstowcs \- convert a multibyte string to a wide-character string
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <stdlib.h>
  24 .sp
  25 .BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n );
  26 .fi
  27 .SH DESCRIPTION
  28 If
  29 .I dest
  30 is not NULL,
  31 the
  32 .BR mbstowcs ()
  33 function converts the
  34 multibyte string
  35 .I src
  36 to a wide-character string starting at
  37 .IR dest .
  38 At most
  39 .I n
  40 wide characters are written to
  41 .IR dest .
  42 The conversion starts
  43 in the initial state.
  44 The conversion can stop for three reasons:
  45 .IP 1. 3
  46 An invalid multibyte sequence has been encountered.
  47 In this case,
  48 .I (size_t)\ \-1
  49 is returned.
  50 .IP 2.
  51 .I n
  52 non-L\(aq\\0\(aq wide characters have been stored at
  53 .IR dest .
  54 In this case, the number of wide characters written to
  55 .I dest
  56 is returned, but the
  57 shift state at this point is lost.
  58 .IP 3.
  59 The multibyte string has been completely converted, including the
  60 terminating null wide character (\(aq\\0\(aq).
  61 In this case, the number of wide characters written to
  62 .IR dest ,
  63 excluding the terminating null wide character, is returned.
  64 .PP
  65 The programmer must ensure that there is room for at least
  66 .I n
  67 wide
  68 characters at
  69 .IR dest .
  70 .PP
  71 If
  72 .IR dest
  73 is NULL,
  74 .I n
  75 is ignored, and the conversion proceeds as
  76 above, except that the converted wide characters are not written out to memory,
  77 and that no length limit exists.
  78 .PP
  79 In order to avoid the case 2 above, the programmer should make sure
  80 .I n
  81 is
  82 greater than or equal to
  83 .IR "mbstowcs(NULL,src,0)+1" .
  84 .SH RETURN VALUE
  85 The
  86 .BR mbstowcs ()
  87 function returns the number of wide characters that make
  88 up the converted part of the wide-character string, not including the
  89 terminating null wide character.
  90 If an invalid multibyte sequence was
  91 encountered,
  92 .I (size_t)\ \-1
  93 is returned.
  94 .SH CONFORMING TO
  95 C99.
  96 .SH NOTES
  97 The behavior of
  98 .BR mbstowcs ()
  99 depends on the
 100 .B LC_CTYPE
 101 category of the
 102 current locale.
 103 .PP
 104 The function
 105 .BR mbsrtowcs (3)
 106 provides a better interface to the same
 107 functionality.
 108 .SH EXAMPLE
 109 The program below illustrates the use of
 110 .BR mbstowcs (),
 111 as well as some of the wide character classification functions.
 112 An example run is the following:
 113 .in +4n
 114 .nf
 115
 116 $ ./t_mbstowcs de_DE.UTF\-8 Grüße!
 117 Length of source string (excluding terminator):
 118     8 bytes
 119     6 multibyte characters
 120
 121 Wide character string is: Grüße! (6 characters)
 122     G alpha upper
 123     r alpha lower
 124     ü alpha lower
 125     ß alpha lower
 126     e alpha lower
 127     ! !alpha
 128 .fi
 129 .in
 130 .SS Program source
 131 .nf
 132 #include <locale.h>
 133 #include <wchar.h>
 134 #include <stdio.h>
 135 #include <string.h>
 136 #include <stdlib.h>
 137
 138 int
 139 main(int argc, char *argv[])
 140 {
 141     size_t mbslen;      /* Number of multibyte characters in source */
 142     wchar_t *wcs;       /* Pointer to converted wide character string */
 143     wchar_t *wp;
 144
 145     if (argc < 3) {
 146         fprintf(stderr, "Usage: %s <locale> <string>\\n", argv[0]);
 147         exit(EXIT_FAILURE);
 148     }
 149
 150     /* Apply the specified locale */
 151
 152     if (setlocale(LC_ALL, argv[1]) == NULL) {
 153         perror("setlocale");
 154         exit(EXIT_FAILURE);
 155     }
 156
 157     /* Calculate the length required to hold argv[2] converted to
 158        a wide character string */
 159
 160     mbslen = mbstowcs(NULL, argv[2], 0);
 161     if (mbslen == (size_t) \-1) {
 162         perror("mbstowcs");
 163         exit(EXIT_FAILURE);
 164     }
 165
 166     /* Describe the source string to the user */
 167
 168     printf("Length of source string (excluding terminator):\\n");
 169     printf("    %zu bytes\\n", strlen(argv[2]));
 170     printf("    %zu multibyte characters\\n\\n", mbslen);
 171
 172     /* Allocate wide character string of the desired size.  Add 1
 173        to allow for terminating null wide character (L\(aq\\0\(aq). */
 174
 175     wcs = calloc(mbslen + 1, sizeof(wchar_t));
 176     if (wcs == NULL) {
 177         perror("calloc");
 178         exit(EXIT_FAILURE);
 179     }
 180
 181     /* Convert the multibyte character string in argv[2] to a
 182        wide character string */
 183
 184     if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) {
 185         perror("mbstowcs");
 186         exit(EXIT_FAILURE);
 187     }
 188
 189     printf("Wide character string is: %ls (%zu characters)\\n",
 190             wcs, mbslen);
 191
 192     /* Now do some inspection of the classes of the characters in
 193        the wide character string */
 194
 195     for (wp = wcs; *wp != 0; wp++) {
 196         printf("    %lc ", (wint_t) *wp);
 197
 198         if (!iswalpha(*wp))
 199             printf("!");
 200         printf("alpha ");
 201
 202         if (iswalpha(*wp)) {
 203             if (iswupper(*wp))
 204                 printf("upper ");
 205
 206             if (iswlower(*wp))
 207                 printf("lower ");
 208         }
 209
 210         putchar(\(aq\\n\(aq);
 211     }
 212
 213     exit(EXIT_SUCCESS);
 214 }
 215 .fi
 216 .SH SEE ALSO
 217 .BR mblen (3),
 218 .BR mbsrtowcs (3),
 219 .BR mbtowc (3),
 220 .BR wctomb (3),
 221 .BR wcstombs (3)
 222 .SH COLOPHON
 223 This page is part of release 3.79 of the Linux
 224 .I man-pages
 225 project.
 226 A description of the project,
 227 information about reporting bugs,
 228 and the latest version of this page,
 229 can be found at
 230 \%http://www.kernel.org/doc/man\-pages/.