usr/src/man/man3c/mbstowcs.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2017 Nexenta Systems, Inc.
  13 .\"
  14 .Dd March 28, 2017
  15 .Dt MBSTOWCS 3C
  16 .Os
  17 .Sh NAME
  18 .Nm mbstowcs ,
  19 .Nm mbstowcs_l
  20 .Nd convert a multibyte character string to a wide-character string
  21 .Sh LIBRARY
  22 .Lb libc
  23 .Sh SYNOPSIS
  24 .In stdlib.h
  25 .Ft size_t
  26 .Fo mbstowcs
  27 .Fa "wchar_t *restrict pwcs"
  28 .Fa "const char *restrict s"
  29 .Fa "size_t n"
  30 .Fc
  31 .In stdlib.h
  32 .In xlocale.h
  33 .Ft size_t
  34 .Fo mbstowcs_l
  35 .Fa "wchar_t *restrict pwcs"
  36 .Fa "const char *restrict s"
  37 .Fa "size_t n"
  38 .Fa "locale_t loc"
  39 .Fc
  40 .Sh DESCRIPTION
  41 The
  42 .Fn mbstowcs
  43 function converts a multibyte character string
  44 .Fa s
  45 beginning in the initial conversion state into a wide-character string.
  46 If
  47 .Fa pwcs
  48 is not
  49 .Dv NULL ,
  50 the converted characters are stored into array pointed to by
  51 .Fa pwcs .
  52 .Pp
  53 Conversion continues up to and including a terminating null character, which is
  54 also stored, or until
  55 .Fa n
  56 wide-characters have been stored into the array pointed to by
  57 .Fa pwcs .
  58 .Pp
  59 The behavior of
  60 .Fn mbstowcs
  61 function is affected by the
  62 .Ev LC_CTYPE
  63 category of the current locale.
  64 .Pp
  65 The
  66 .Fn mbstowcs_l
  67 function behaves identically to
  68 .Fn mbstowcs ,
  69 except instead of using the current locale, it uses the locale as specified by
  70 .Fa loc .
  71 .Sh RETURN VALUES
  72 The
  73 .Fn mbstowcs
  74 and
  75 .Fn mbstowcs_l
  76 functions return the number of wide-characters successfully converted, not
  77 including the terminating null
  78 .Pq if any ,
  79 or
  80 .Li \-1
  81 if conversion encounters a sequence of bytes that does not form a valid
  82 character.
  83 .Sh ERRORS
  84 The
  85 .Fn mbstowcs
  86 and
  87 .Fn mbstowcs_l
  88 functions will fail if:
  89 .Bl -tag -width Er
  90 .It Er EILSEQ
  91 An invalid multibyte sequence was detected.
  92 .It Er EINVAL
  93 The conversion state is invalid.
  94 .El
  95 .Sh INTERFACE STABILITY
  96 The
  97 .Fn mbstowcs
  98 function is
  99 .Sy Standard .
 100 The
 101 .Fn mbstowcs_l
 102 function is
 103 .Sy Uncommitted .
 104 .Sh MT-LEVEL
 105 .Sy MT-Safe
 106 .Sh SEE ALSO
 107 .Xr mbsnrtowcs 3C ,
 108 .Xr mbtowc 3C ,
 109 .Xr newlocale 3C ,
 110 .Xr setlocale 3C ,
 111 .Xr uselocale 3C ,
 112 .Xr wcstombs 3C ,
 113 .Xr attributes 5 ,
 114 .Xr environ 5 ,
 115 .Xr standards 5