draft/man3/wcrtomb.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   GNU glibc-2 source code and manual
  10 .\"   Dinkumware C library reference http://www.dinkumware.com/
  11 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  12 .\"   ISO/IEC 9899:1999
  13 .\"
  14 .\" About this Japanese page, please contact to JM Project <JM@linux.or.jp>
  15 .\" Translated Mon Oct 25 22:55:40 JST 1999
  16 .\"           by FUJIWARA Teruyoshi <fujiwara@linux.or.jp>
  17 .\"
  18 .TH WCRTOMB 3  2011-09-28 "GNU" "Linux Programmer's Manual"
  19 .\"O .SH NAME
  20 .SH Ì¾Á°
  21 .\"O wcrtomb \- convert a wide character to a multibyte sequence
  22 wcrtomb \- ¥ï¥¤¥ÉÊ¸»ú 1 ¤Ä¤ò¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ËÊÑ´¹¤¹¤ë
  23 .\"O .SH SYNOPSIS
  24 .SH ½ñ¼°
  25 .nf
  26 .B #include <wchar.h>
  27 .sp
  28 .BI "size_t wcrtomb(char *" s ", wchar_t " wc ", mbstate_t *" ps );
  29 .fi
  30 .\"O .SH DESCRIPTION
  31 .SH ÀâÌÀ
  32 .\"O The main case for this function is when \fIs\fP is
  33 .\"O not NULL and \fIwc\fP is not a null wide character (L\(aq\\0\(aq).
  34 ¤³¤Î´Ø¿ô¤¬¼ç¤Ë»È¤ï¤ì¤ë¤Î¤Ï¡¢\fIs\fP ¤¬ NULL ¤Ç¤Ê¤¯¡¢
  35 \fIwc\fP ¤¬ NULL ¥ï¥¤¥ÉÊ¸»ú (L\(aq\\0\(aq) ¤Ç¤Ê¤¤¾ì¹ç¤Ç¤¢¤ë¡£
  36 .\"O In this case, the
  37 .\"O .BR wcrtomb ()
  38 .\"O function
  39 .\"O converts the wide character \fIwc\fP
  40 .\"O to its multibyte representation and stores it
  41 .\"O at the beginning of the character
  42 .\"O array pointed to by \fIs\fP.
  43 .\"O It updates the shift state \fI*ps\fP, and
  44 .\"O returns the length of said multibyte representation,
  45 .\"O that is, the number of bytes
  46 .\"O written at \fIs\fP.
  47 ¤³¤Î¾ì¹ç¤Ë¤Ï¡¢
  48 .BR wcrtomb ()
  49 ´Ø¿ô¤Ï¥ï¥¤¥ÉÊ¸»ú \fIwc\fP ¤ò¥Þ¥ë¥Á¥Ð¥¤¥ÈÉ½
  50 ¸½¤ËÊÑ´¹¤·¡¢\fIs\fP ¤¬»Ø¤¹ char ·¿¤ÎÇÛÎó¤Ë¤³¤ì¤ò³ÊÇ¼¤¹¤ë¡£¤³¤Î´Ø¿ô¤Ï
  51 ¥·¥Õ¥È¾õÂÖ \fI*ps\fP ¤ò¹¹¿·¤·¡¢½ÐÎÏ¤µ¤ì¤¿¥Þ¥ë¥Á¥Ð¥¤¥ÈÉ½¸½¤ÎÄ¹¤µ¡¢¤¹¤Ê
  52 ¤ï¤Á \fIs\fP ¤Ë½ñ¤¹þ¤Þ¤ì¤¿¥Ð¥¤¥È¿ô¤òÊÖ¤¹¡£
  53 .PP
  54 .\"O A different case is when \fIs\fP is not NULL,
  55 .\"O but \fIwc\fP is a null wide character (L\(aq\\0\(aq).
  56 .\"O In this
  57 .\"O case the
  58 .\"O .BR wcrtomb ()
  59 .\"O function stores at
  60 .\"O the character array pointed to by
  61 .\"O \fIs\fP the shift sequence needed to
  62 .\"O bring \fI*ps\fP back to the initial state,
  63 .\"O followed by a \(aq\\0\(aq byte.
  64 .\"O It updates the shift state \fI*ps\fP (i.e., brings
  65 .\"O it into the initial state),
  66 .\"O and returns the length of the shift sequence plus
  67 .\"O one, that is, the number of bytes written at \fIs\fP.
  68 ÊÌ¤Î¥±¡¼¥¹¤È¤·¤Æ¤Ï¡¢\fIs\fP ¤Ï NULL ¤Ç¤Ê¤¤¤¬
  69 \fIwc\fP ¤¬ NULL ¥ï¥¤¥ÉÊ¸»ú (L\(aq\\0\(aq) ¤Î¤³¤È¤¬¤¢¤ë¡£
  70 ¤³¤Î¾ì¹ç¤Î
  71 .BR wcrtomb ()
  72 ´Ø¿ô¤Ï¡¢\fI*ps\fP ¤ò½é´ü¾õÂÖ¤ËÌá¤¹¤Î¤ËÉ¬
  73 Í×¤Ê¥·¥Õ¥È¥·¡¼¥±¥ó¥¹¤ò \fIs\fP ¤¬»Ø¤¹ char ·¿ÇÛÎó¤Ë³ÊÇ¼¤·¡¢¤½¤Î¸å¤Ë \(aq\\0\(aq
  74 ¤ò³ÊÇ¼¤¹¤ë¡£¤³¤Î´Ø¿ô¤Ï¥·¥Õ¥È¾õÂÖ \fI*ps\fP ¤ò¹¹¿·¤·(¤Ä¤Þ¤ê½é´ü¾õÂÖ¤ËÌá
  75 ¤·)¡¢¥·¥Õ¥È¥·¡¼¥±¥ó¥¹¤ÎÄ¹¤µ¤Ë 1 ¤ò²Ã¤¨¤¿ÃÍ¤òÊÖ¤¹¡£¤³¤ÎÃÍ¤Ï \fIs\fP ¤Ë
  76 ½ñ¤¹þ¤Þ¤ì¤¿¥Ð¥¤¥È¿ô¤Ç¤¢¤ë¡£
  77 .PP
  78 .\"O A third case is when \fIs\fP is NULL.
  79 .\"O In this case \fIwc\fP is ignored,
  80 .\"O and the function effectively returns
  81 .\"O
  82 .\"O     wcrtomb(buf, L\(aq\\0\(aq, ps)
  83 .\"O
  84 .\"O where
  85 .\"O .I buf
  86 .\"O is an internal anonymous buffer.
  87 »°ÈÖÌÜ¤Î¥±¡¼¥¹¤Ï¡¢\fIs\fP ¤¬ NULL ¤Î»þ¤Ç¤¢¤ë¡£
  88 ¤³¤Î¾ì¹ç¤Ë¤Ï \fIwc\fP ¤ÏÌµ»ë¤µ¤ì¡¢´Ø¿ô¤Î¼ÂºÝ¤ÎÆ°¤¤È¤·¤Æ¤Ï
  89
  90     wcrtomb(buf, L\(aq\\0\(aq, ps)
  91
  92 ¤¬ÊÖ¤µ¤ì¤ë¡£¤³¤³¤Ç¡¢
  93 .I buf
  94 ¤ÏÆâÉôÅª¤ÊÌµÌ¾¥Ð¥Ã¥Õ¥¡¤Ç¤¢¤ë¡£
  95
  96 .PP
  97 .\"O In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous
  98 .\"O state only known to the
  99 .\"O .BR wcrtomb ()
 100 .\"O function is used instead.
 101 °Ê¾å¤Î¤¤¤º¤ì¤Î¾ì¹ç¤â¡¢\fIps\fP ¤¬ NULL ¥Ý¥¤¥ó¥¿¤Ê¤é¤Ð¥·¥Õ¥È¾õÂÖ¤ÏÍÑ¤¤
 102 ¤é¤ì¤º¡¢
 103 .BR wcrtomb ()
 104 ´Ø¿ô¤À¤±¤¬ÃÎ¤Ã¤Æ¤¤¤ëÀÅÅª¤ÊÆ¿Ì¾¤Î¾õÂÖ¤¬»È¤ï¤ì¤ë¡£
 105 .\"O .SH "RETURN VALUE"
 106 .SH ÊÖ¤êÃÍ
 107 .\"O The
 108 .\"O .BR wcrtomb ()
 109 .\"O function returns the number of
 110 .\"O bytes that have been or would
 111 .\"O have been written to the byte array at \fIs\fP.
 112 .\"O If \fIwc\fP can not be
 113 .\"O represented as a multibyte sequence (according to the current locale),
 114 .\"O .I (size_t)\ \-1
 115 .\"O is returned, and \fIerrno\fP set to \fBEILSEQ\fP.
 116 .BR wcrtomb ()
 117 ´Ø¿ô¤Ï¡¢\fIs\fP ¤¬»Ø¤¹¥Ð¥¤¥ÈÎó¤Ë½ñ¤¹þ¤Þ¤ì¤¿¥Ð¥¤¥È¿ô¡¢¤¢
 118 ¤ë¤¤¤Ï½ñ¤¹þ¤Þ¤ì¤¿¤Ç¤¢¤í¤¦¥Ð¥¤¥È¿ô¤òÊÖ¤¹¡£\fIwc\fP ¤ò(¸½ºß¤Î¥í¥±¡¼¥ë¤Ë
 119 ½¾¤Ã¤Æ)¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ÇÉ½¸½¤Ç¤¤Ê¤±¤ì¤Ð¡¢
 120 .I (size_t)\ \-1
 121 ¤¬ÊÖ¤µ¤ì¡¢ \fIerrno\fP ¤Ë \fBEILSEQ\fP ¤¬ÀßÄê¤µ¤ì¤ë¡£
 122 .\"O .SH "CONFORMING TO"
 123 .SH ½àµò
 124 C99.
 125 .\"O .SH NOTES
 126 .SH Ãí°Õ
 127 .\"O The behavior of
 128 .\"O .BR wcrtomb ()
 129 .\"O depends on the
 130 .\"O .B LC_CTYPE
 131 .\"O category of the
 132 .\"O current locale.
 133 .BR wcrtomb ()
 134 ¤ÎÆ°ºî¤Ï¡¢¸½ºß¤Î¥í¥±¡¼¥ë¤Î
 135 .B LC_CTYPE
 136 ¥«¥Æ¥´¥ê¤Ë°ÍÂ¸¤¹¤ë¡£
 137 .PP
 138 .\"O Passing NULL as \fIps\fP is not multithread safe.
 139 \fIps\fP ¤Ë NULL ¤òÅÏ¤·¤¿ºÝ¤ÎÆ°ºî¤Ï¥Þ¥ë¥Á¥¹¥ì¥Ã¥É¥»¡¼¥Õ¤Ç¤Ê¤¤¡£
 140 .\"O .SH "SEE ALSO"
 141 .SH ´ØÏ¢¹àÌÜ
 142 .BR wcsrtombs (3)