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  2011-09-28 "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
  56 case the
  57 .BR wcrtomb ()
  58 function stores at
  59 the character array pointed to by
  60 .I s
  61 the shift sequence needed to
  62 bring
  63 .I *ps
  64 back to the initial state,
  65 followed by a \(aq\\0\(aq byte.
  66 It updates the shift state
  67 .I *ps
  68 (i.e., brings
  69 it into the initial state),
  70 and returns the length of the shift sequence plus
  71 one, that is, the number of bytes written at
  72 .IR s .
  73 .PP
  74 A third case is when
  75 .I s
  76 is NULL.
  77 In this case
  78 .I wc
  79 is ignored,
  80 and the function effectively returns
  81
  82     wcrtomb(buf, L\(aq\\0\(aq, ps)
  83
  84 where
  85 .I buf
  86 is an internal anonymous buffer.
  87 .PP
  88 In all of the above cases, if
  89 .I ps
  90 is a NULL pointer, a static anonymous
  91 state known only to the
  92 .BR wcrtomb ()
  93 function is used instead.
  94 .SH RETURN VALUE
  95 The
  96 .BR wcrtomb ()
  97 function returns the number of
  98 bytes that have been or would
  99 have been written to the byte array at
 100 .IR s .
 101 If
 102 .I wc
 103 can not be
 104 represented as a multibyte sequence (according to the current locale),
 105 .I (size_t)\ \-1
 106 is returned, and
 107 .I errno
 108 set to
 109 .BR EILSEQ .
 110 .SH CONFORMING TO
 111 C99.
 112 .SH NOTES
 113 The behavior of
 114 .BR wcrtomb ()
 115 depends on the
 116 .B LC_CTYPE
 117 category of the
 118 current locale.
 119 .PP
 120 Passing NULL as
 121 .I ps
 122 is not multithread safe.
 123 .SH SEE ALSO
 124 .BR wcsrtombs (3)