usr/src/man/man3c/wcstombs.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 WCSTOMBS 3C
  16 .Os
  17 .Sh NAME
  18 .Nm wcstombs ,
  19 .Nm wcstombs_l
  20 .Nd convert a wide-character string to a multibyte character string
  21 .Sh LIBRARY
  22 .Lb libc
  23 .Sh SYNOPSIS
  24 .In stdlib.h
  25 .Ft size_t
  26 .Fo wcstombs
  27 .Fa "char *restrict s"
  28 .Fa "const wchar_t *restrict pwcs"
  29 .Fa "size_t n"
  30 .Fc
  31 .In stdlib.h
  32 .In xlocale.h
  33 .Ft size_t
  34 .Fo wcstombs_l
  35 .Fa "char *restrict s"
  36 .Fa "const wchar_t *restrict pwcs"
  37 .Fa "size_t n"
  38 .Fa "locale_t loc"
  39 .Fc
  40 .Sh DESCRIPTION
  41 The
  42 .Fn wcstombs
  43 function converts a wide-character string
  44 .Fa pwcs
  45 into a multibyte character string, beginning in the initial conversion state.
  46 If
  47 .Fa s
  48 is not
  49 .Dv NULL ,
  50 converted characters are stored into the array pointed to by
  51 .Fa s .
  52 .Pp
  53 Conversion continues up to and including a terminating null wide-character,
  54 which is also stored, or until
  55 .Fa n
  56 bytes have been stored into the array pointed to by
  57 .Fa s .
  58 If the latter case results in partial multibyte character at the end of the
  59 string, it is not stored.
  60 .Pp
  61 The behavior of
  62 .Fn wcstombs
  63 function is affected by the
  64 .Ev LC_CTYPE
  65 category of the current locale.
  66 .Pp
  67 The
  68 .Fn wcstombs_l
  69 function behaves identically to
  70 .Fn wcstombs ,
  71 except instead of using the current locale, it uses the locale as specified by
  72 .Fa loc .
  73 .Sh RETURN VALUES
  74 The
  75 .Fn wcstombs
  76 and
  77 .Fn wcstombs_l
  78 functions return the number of bytes in the resulting character sequence, not
  79 including the terminating null
  80 .Pq if any ,
  81 or
  82 .Li \-1
  83 if a code is reached that does not correspond to a valid character.
  84 .Sh ERRORS
  85 The
  86 .Fn wcstombs
  87 and
  88 .Fn wcstombs_l
  89 functions will fail if:
  90 .Bl -tag -width Er
  91 .It Er EILSEQ
  92 A wide-character code does not correspond to a valid character.
  93 .It Er EINVAL
  94 The conversion state is invalid.
  95 .El
  96 .Sh INTERFACE STABILITY
  97 The
  98 .Fn wcstombs
  99 function is
 100 .Sy Standard .
 101 The
 102 .Fn wcstombs_l
 103 function is
 104 .Sy Uncommitted .
 105 .Sh MT-LEVEL
 106 .Sy MT-Safe
 107 .Sh SEE ALSO
 108 .Xr mbstowcs 3C ,
 109 .Xr newlocale 3C ,
 110 .Xr setlocale 3C ,
 111 .Xr uselocale 3C ,
 112 .Xr wcsnrtombs 3C ,
 113 .Xr wctomb 3C ,
 114 .Xr attributes 5 ,
 115 .Xr environ 5 ,
 116 .Xr standards 5