original/man3/wcrtomb.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 .\"   ISO/IEC 9899:1999
  15 .\"
  16 .TH WCRTOMB 3  2014-03-18 "GNU" "Linux Programmer's Manual"
  17 .SH NAME
  18 wcrtomb \- convert a wide character to a multibyte sequence
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <wchar.h>
  22 .sp
  23 .BI "size_t wcrtomb(char *" s ", wchar_t " wc ", mbstate_t *" ps );
  24 .fi
  25 .SH DESCRIPTION
  26 The main case for this function is when
  27 .I s
  28 is
  29 not NULL and
  30 .I wc
  31 is not a null wide character (L\(aq\\0\(aq).
  32 In this case, the
  33 .BR wcrtomb ()
  34 function
  35 converts the wide character
  36 .I wc
  37 to its multibyte representation and stores it
  38 at the beginning of the character
  39 array pointed to by
  40 .IR s .
  41 It updates the shift state
  42 .IR *ps ,
  43 and
  44 returns the length of said multibyte representation,
  45 that is, the number of bytes
  46 written at
  47 .IR s .
  48 .PP
  49 A different case is when
  50 .I s
  51 is not NULL,
  52 but
  53 .I wc
  54 is a null wide character (L\(aq\\0\(aq).
  55 In this case, the
  56 .BR wcrtomb ()
  57 function stores at
  58 the character array pointed to by
  59 .I s
  60 the shift sequence needed to
  61 bring
  62 .I *ps
  63 back to the initial state,
  64 followed by a \(aq\\0\(aq byte.
  65 It updates the shift state
  66 .I *ps
  67 (i.e., brings
  68 it into the initial state),
  69 and returns the length of the shift sequence plus
  70 one, that is, the number of bytes written at
  71 .IR s .
  72 .PP
  73 A third case is when
  74 .I s
  75 is NULL.
  76 In this case,
  77 .I wc
  78 is ignored,
  79 and the function effectively returns
  80
  81     wcrtomb(buf, L\(aq\\0\(aq, ps)
  82
  83 where
  84 .I buf
  85 is an internal anonymous buffer.
  86 .PP
  87 In all of the above cases, if
  88 .I ps
  89 is NULL, a static anonymous
  90 state known only to the
  91 .BR wcrtomb ()
  92 function is used instead.
  93 .SH RETURN VALUE
  94 The
  95 .BR wcrtomb ()
  96 function returns the number of
  97 bytes that have been or would
  98 have been written to the byte array at
  99 .IR s .
 100 If
 101 .I wc
 102 can not be
 103 represented as a multibyte sequence (according to the current locale),
 104 .I (size_t)\ \-1
 105 is returned, and
 106 .I errno
 107 set to
 108 .BR EILSEQ .
 109 .SH CONFORMING TO
 110 C99.
 111 .SH NOTES
 112 The behavior of
 113 .BR wcrtomb ()
 114 depends on the
 115 .B LC_CTYPE
 116 category of the
 117 current locale.
 118 .PP
 119 Passing NULL as
 120 .I ps
 121 is not multithread safe.
 122 .SH SEE ALSO
 123 .BR mbsinit (3),
 124 .BR wcsrtombs (3)
 125 .SH COLOPHON
 126 This page is part of release 3.79 of the Linux
 127 .I man-pages
 128 project.
 129 A description of the project,
 130 information about reporting bugs,
 131 and the latest version of this page,
 132 can be found at
 133 \%http://www.kernel.org/doc/man\-pages/.