draft/man3/wcsrtombs.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 Sat Oct 23 15:38:11 JST 1999
  16 .\"           by FUJIWARA Teruyoshi <fujiwara@linux.or.jp>
  17 .\"
  18 .TH WCSRTOMBS 3  2011-09-28 "GNU" "Linux Programmer's Manual"
  19 .\"O .SH NAME
  20 .SH Ì¾Á°
  21 .\"O wcsrtombs \- convert a wide-character string to a multibyte string
  22 wcsrtombs \- ¥ï¥¤¥ÉÊ¸»úÊ¸»úÎó¤ò¥Þ¥ë¥Á¥Ð¥¤¥ÈÊ¸»úÎó¤ËÊÑ´¹¤¹¤ë
  23 .\"O .SH SYNOPSIS
  24 .SH ½ñ¼°
  25 .nf
  26 .B #include <wchar.h>
  27 .sp
  28 .BI "size_t wcsrtombs(char *" dest ", const wchar_t **" src ,
  29 .BI "                 size_t " len ", mbstate_t *" ps );
  30 .fi
  31 .\"O .SH DESCRIPTION
  32 .SH ÀâÌÀ
  33 .\"O If \fIdest\fP is not a NULL pointer,
  34 .\"O the
  35 .\"O .BR wcsrtombs ()
  36 .\"O function converts
  37 .\"O the wide-character string \fI*src\fP to a multibyte string starting at
  38 .\"O \fIdest\fP.
  39 .\"O At most \fIlen\fP bytes are written to \fIdest\fP.
  40 .\"O The shift state
  41 .\"O \fI*ps\fP is updated.
  42 .\"O The conversion is effectively performed by repeatedly
  43 .\"O calling
  44 .\"O .IR "wcrtomb(dest, *src, ps)" ,
  45 .\"O as long as this call succeeds,
  46 .\"O and then incrementing \fIdest\fP by the
  47 .\"O number of bytes written and \fI*src\fP
  48 .\"O by one.
  49 .\"O The conversion can stop for three reasons:
  50 \fIdest\fP ¤¬ NULL ¥Ý¥¤¥ó¥¿¤Ç¤Ê¤±¤ì¤Ð¡¢
  51 .BR wcsrtombs ()
  52 ´Ø¿ô¤Ï
  53 ¥ï¥¤¥ÉÊ¸»úÊ¸»úÎó \fI*src\fP ¤ò \fIdest\fP ¤¬»Ø¤¹¥Þ¥ë¥Á¥Ð¥¤¥ÈÊ¸»úÎó
  54 ¤ËÊÑ´¹¤¹¤ë¡£ºÇÂç \fIlen\fP ¥Ð¥¤¥È¤Þ¤Ç¤¬ \fIdest\fP ¤Ë½ñ¤¹þ¤Þ¤ì¤ë¡£
  55 ¥·¥Õ¥È¾õÂÖ \fI*ps\fP ¤Ï¹¹¿·¤µ¤ì¤ë¡£¼ÂºÝ¤Î¸ú²Ì¤È¤·¤Æ¤Ï¡¢¤³¤ÎÊÑ´¹¤Ï°Ê²¼
  56 ¤ÎÆ°ºî¤ÈÆ±¤¸¤Ë¤Ê¤ë:
  57 .IR "wcrtomb(dest, *src, ps)"
  58 ¤ò¸Æ¤Ó¡¢À®¸ù¤¬ÊÖ¤Ã¤¿¤é¡¢
  59 \fIdest\fP ¤ò½ñ¤¹þ¤ó¤À¥Ð¥¤¥È¿ô¤À¤±Áý¤ä¤·¡¢\fI*src\fP ¤ò 1 Áý¤ä¤¹¡£
  60 ¤½¤·¤Æ¡¢wcrtomb ¤¬À®¸ù¤òÊÖ¤¹¸Â¤ê¤³¤ì¤ò·«¤êÊÖ¤¹¡£
  61 ÊÑ´¹¤¬»ß¤Þ¤ëÍýÍ³¤Ï 3 ¤Ä¹Í¤¨¤é¤ì¤ë:
  62 .PP
  63 .\"O 1. A wide character has been encountered that can not be represented as a
  64 .\"O multibyte sequence (according to the current locale).
  65 .\"O In this case \fI*src\fP
  66 .\"O is left pointing to the invalid wide character,
  67 .\"O .I (size_t)\ \-1
  68 .\"O is returned,
  69 .\"O and
  70 .\"O .I errno
  71 .\"O is set to \fBEILSEQ\fP.
  72 (¸½ºß¤Î¥í¥±¡¼¥ë¤Ë´ð¤Å¤¤¤Æ)¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ÇÉ½¸½¤Ç¤¤Ê¤¤¥ï¥¤¥ÉÊ¸»ú¤Ë
  73 ½Ð²ñ¤Ã¤¿¾ì¹ç¡£¤³¤Î¾ì¹ç¤Ï¡¢\fI*src\fP ¤ÏÉÔÀµ¤Ê¥ï¥¤¥ÉÊ¸»ú¤ò»Ø¤·¤¿¾õÂÖ¤Ë¤Ê¤ê¡¢
  74 .I (size_t)\ \-1
  75 ¤¬ÊÖ¤µ¤ì¡¢
  76 .I errno
  77 ¤Ë \fBEILSEQ\fP ¤¬ÀßÄê¤µ¤ì¤ë¡£
  78 .PP
  79 .\"O 2. The length limit forces a stop.
  80 .\"O In this case \fI*src\fP is left pointing
  81 .\"O to the next wide character to be converted,
  82 .\"O and the number of bytes written to
  83 .\"O \fIdest\fP is returned.
  84 2. Ä¹¤µ¤ÎÀ©¸Â¤Ë¤è¤êÊÑ´¹¤¬»ß¤á¤é¤ì¤¿¾ì¹ç¡£¤³¤Î¾ì¹ç¤Ë¤Ï¡¢\fI*src\fP ¤Ï¼¡¤Ë
  85 ÊÑ´¹¤µ¤ì¤ë¤Ù¤¥ï¥¤¥ÉÊ¸»úÎó¤ò»Ø¤·¤¿¾õÂÖ¤Ë¤Ê¤ê¡¢\fIdest\fP ¤Ë½ñ¤¹þ¤Þ¤ì
  86 ¤¿¥Ð¥¤¥È¿ô¤¬ÊÖ¤µ¤ì¤ë¡£
  87 .PP
  88 .\"O 3. The wide-character string has been completely converted, including the
  89 .\"O terminating null wide character (L\(aq\\0\(aq),
  90 .\"O which has the side effect of bringing back \fI*ps\fP
  91 .\"O to the initial state.
  92 .\"O In this case \fI*src\fP is set to NULL, and the number
  93 .\"O of bytes written to \fIdest\fP, excluding the terminating null, is returned.
  94 3. ¥ï¥¤¥ÉÊ¸»úÎó¤¬½ªÃ¼¤Î NULL ¥ï¥¤¥ÉÊ¸»ú (L\(aq\\0\(aq) ¤â´Þ¤á¤ÆÁ´¤Æ
  95 ÊÑ´¹¤µ¤ì¤¿¾ì¹ç¡£¤³¤ÎºÝ¡¢\fI*ps\fP ¤¬½é´ü¾õÂÖ¤ËÌá¤ë¤È¤¤¤¦ÉûºîÍÑ¤¬¤¢¤ë¡£
  96 ¤³¤Î¾ì¹ç¤Ë¤Ï \fI*src\fP ¤Ë NULL ¤¬ÀßÄê¤µ¤ì¡¢\fIdest\fP ¤Ë½ñ¤¹þ¤Þ¤ì¤¿
  97 ¥Ð¥¤¥È¿ô¤¬ÊÖ¤µ¤ì¤ë (½ªÃ¼¤Î NULL ¤Ï¿ô¤¨¤Ê¤¤)¡£
  98 .PP
  99 .\"O If \fIdest\fP is NULL, \fIlen\fP is ignored,
 100 .\"O and the conversion proceeds as above, except that the converted bytes
 101 .\"O are not written out to memory, and that
 102 .\"O no length limit exists.
 103 \fIdest\fP ¤¬ NULL ¤Ê¤é¤Ð \fIlen\fP ¤ÏÌµ»ë¤µ¤ì¤ÆÁ°½Ò¤Î¤è¤¦¤ËÊÑ´¹¤¬¹Ô¤ï
 104 ¤ì¤ë¤¬¡¢ÊÑ´¹¤µ¤ì¤¿¥Ð¥¤¥È¥Ç¡¼¥¿¤Ï¥á¥â¥ê¤Ë½ñ¤½Ð¤µ¤ì¤Ê¤¤ÅÀ¤È¡¢½ÐÎÏÀè¤ÎÄ¹
 105 ¤µ¤ÎÀ©¸Â¤¬¤Ê¤¤ÅÀ¤¬°Û¤Ê¤ë¡£
 106 .PP
 107 .\"O In both of the above cases,
 108 .\"O if \fIps\fP is a NULL pointer, a static anonymous
 109 .\"O state only known to the wcsrtombs function is used instead.
 110 ¾åµ¤Î¤¤¤º¤ì¤Î¾ì¹ç¤â¡¢\fIps\fP ¤¬ NULL ¥Ý¥¤¥ó¥¿¤Ê¤é¤Ð¡¢wcsnrtombs ´Ø¿ô
 111 ¤À¤±¤¬ÃÎ¤Ã¤Æ¤¤¤ëÀÅÅª¤ÊÆ¿Ì¾¤Î¾õÂÖ¤¬¥·¥Õ¥È¾õÂÖ¤ÎÂå¤ï¤ê¤ËÍÑ¤¤¤é¤ì¤ë¡£
 112 .PP
 113 .\"O The programmer must ensure that there is room for at least \fIlen\fP bytes
 114 .\"O at \fIdest\fP.
 115 ¥×¥í¥°¥é¥Þ¤Ï¾¯¤Ê¤¯¤È¤â \fIlen\fP ¥Ð¥¤¥È¤ÎÎÎ°è¤ò \fIdest\fP ¤Ë³ÎÊÝ¤·¤Ê
 116 ¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
 117 .\"O .SH "RETURN VALUE"
 118 .SH ÊÖ¤êÃÍ
 119 .\"O The
 120 .\"O .BR wcsrtombs ()
 121 .\"O function returns
 122 .\"O the number of bytes that make up the
 123 .\"O converted part of multibyte sequence,
 124 .\"O not including the terminating null byte.
 125 .BR wcsrtombs ()
 126 ¤Ï¡¢ÊÑ´¹¤·¤ÆÆÀ¤é¤ì¤¿¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤Î¥Ð¥¤¥È¿ô¤òÊÖ¤¹¡£
 127 ¤³¤ì¤Ë¤Ï½ªÃ¼¤Î null ¥Ð¥¤¥È¤Ï´Þ¤Þ¤ì¤Ê¤¤¡£
 128 .\"O If a wide character was encountered
 129 .\"O which could not be converted,
 130 .\"O .I (size_t)\ \-1
 131 .\"O is returned, and
 132 .\"O .I errno
 133 .\"O set to \fBEILSEQ\fP.
 134 ÊÑ´¹¤Ç¤¤Ê¤¤¥ï¥¤¥ÉÊ¸»ú¤Ë½Ð²ñ¤Ã¤¿¾ì¹ç¤Ë¤Ï
 135 .I (size_t)\ \-1
 136 ¤¬ÊÖ¤µ¤ì¡¢
 137 .I errno
 138 ¤Ë \fBEILSEQ\fP ¤¬ÀßÄê¤µ¤ì¤ë¡£
 139 .\"O .SH "CONFORMING TO"
 140 .SH ½àµò
 141 C99.
 142 .\"O .SH NOTES
 143 .\"O The behavior of
 144 .\"O .BR wcsrtombs ()
 145 .\"O depends on the
 146 .\"O .B LC_CTYPE
 147 .\"O category of the
 148 .\"O current locale.
 149 .BR wcsrtombs ()
 150 ¤ÎÆ°ºî¤Ï¸½ºß¤Î¥í¥±¡¼¥ë¤Î
 151 .B LC_CTYPE
 152 ¥«¥Æ¥´¥ê¤Ë°ÍÂ¸¤¹¤ë¡£
 153 .PP
 154 .\"O Passing NULL as \fIps\fP is not multithread safe.
 155 \fIps\fP ¤Ë NULL ¤òÅÏ¤·¤¿ºÝ¤ÎÆ°ºî¤Ï¥Þ¥ë¥Á¥¹¥ì¥Ã¥É¥»¡¼¥Õ¤Ç¤Ê¤¤¡£
 156 .\"O .SH "SEE ALSO"
 157 .SH ´ØÏ¢¹àÌÜ
 158 .BR iconv (3),
 159 .BR wcsnrtombs (3),
 160 .BR wcstombs (3)