manual/LDP_man-pages/draft/man3/wcstombs.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 .\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
  15 .\"         all rights reserved.
  16 .\" Translated Tue Jan 11 00:55:41 JST 2000
  17 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  18 .\"
  19 .TH WCSTOMBS 3  1999-07-25 "GNU" "Linux Programmer's Manual"
  20 .\"O .SH NAME
  21 .SH Ì¾Á°
  22 .\"O wcstombs \- convert a wide-character string to a multibyte string
  23 wcstombs \- ¥ï¥¤¥ÉÊ¸»úÎó¤ò¥Þ¥ë¥Á¥Ð¥¤¥ÈÊ¸»úÎó¤ËÊÑ´¹¤¹¤ë
  24 .\"O .SH SYNOPSIS
  25 .SH ½ñ¼°
  26 .nf
  27 .B #include <stdlib.h>
  28 .sp
  29 .BI "size_t wcstombs(char *" dest ", const wchar_t *" src ", size_t " n );
  30 .fi
  31 .\"O .SH DESCRIPTION
  32 .SH ÀâÌÀ
  33 .\"O If \fIdest\fP is not a NULL pointer, the
  34 .\"O .BR wcstombs ()
  35 .\"O function converts
  36 .\"O the wide-character string \fIsrc\fP to a multibyte string starting at
  37 .\"O \fIdest\fP.
  38 .\"O At most \fIn\fP bytes are written to \fIdest\fP.
  39 .\"O The conversion
  40 .\"O starts in the initial state.
  41 .\"O The conversion can stop for three reasons:
  42 \fIdest\fP ¤¬ NULL ¥Ý¥¤¥ó¥¿¤Ç¤Ê¤¤¾ì¹ç¡¢
  43 .BR wcstombs ()
  44 ´Ø¿ô¤Ï
  45 ¥ï¥¤¥ÉÊ¸»úÎó \fIsrc\fP ¤ò \fIdest\fP ¤«¤é»Ï¤Þ¤ë¥Þ¥ë¥Á¥Ð¥¤¥ÈÊ¸»úÎó¤Ë
  46 ÊÑ´¹¤¹¤ë¡£\fIdest\fP ¤Ë¤ÏºÇÂç¤Ç \fIn\fP ¥Ð¥¤¥È¤¬½ñ¤¹þ¤Þ¤ì¤ë¡£
  47 ÊÑ´¹¤Ï½é´ü¾õÂÖ¤Ç³«»Ï¤µ¤ì¤ë¡£ÊÑ´¹¤Ï°Ê²¼¤Î3¤Ä¤ÎÍýÍ³¤Ë¤è¤êÄä»ß¤¹¤ë¡£
  48 .PP
  49 .\"O 1. A wide character has been encountered that can not be represented as a
  50 .\"O multibyte sequence (according to the current locale).
  51 .\"O In this case
  52 .\"O .I (size_t)\ \-1
  53 .\"O is returned.
  54 1. (¸½ºß¤Î¥í¥±¡¼¥ë¤Ë¤ª¤±¤ë)¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ÇÉ½¸½¤Ç¤¤Ê¤¤¥ï¥¤¥ÉÊ¸»ú¤Ë
  55 Áø¶ø¤·¤¿¾ì¹ç¡£¤³¤Î¾ì¹ç¤Ë¤Ï
  56 .I (size_t)\ \-1
  57 ¤¬ÊÖ¤µ¤ì¤ë¡£
  58 .PP
  59 .\"O 2. The length limit forces a stop.
  60 .\"O In this case the number of bytes written to
  61 .\"O \fIdest\fP is returned, but the shift state at this point is lost.
  62 2. Ä¹¤µÀ©¸Â¤Ë¤è¤Ã¤Æ¶¯À©Ää»ß¤µ¤»¤é¤ì¤¿¾ì¹ç¡£¤³¤Î¾ì¹ç¤Ë¤Ï \fIdest\fP ¤Ë
  63 ½ñ¤¹þ¤Þ¤ì¤¿¥Ð¥¤¥È¿ô¤¬ÊÖ¤µ¤ì¤ë¡£¤·¤«¤·¤³¤Î»þÅÀ¤Ç¤Î¥·¥Õ¥È¾õÂÖ¤Ï¼º¤ï¤ì¤ë¡£
  64 .PP
  65 .\"O 3. The wide-character string has been completely converted, including the
  66 .\"O terminating L\(aq\\0\(aq.
  67 .\"O In this case the conversion ends in the initial state.
  68 .\"O The number of bytes written to \fIdest\fP,
  69 .\"O excluding the terminating \(aq\\0\(aq byte, is returned.
  70 3. ¥ï¥¤¥ÉÊ¸»úÎó¤¬½ªÃ¼¤Î L\(aq\\0\(aq ¤ò´Þ¤á¤Æ´°Á´¤ËÊÑ´¹¤µ¤ì¤¿¾ì¹ç¡£
  71 ¤³¤Î¾ì¹ç¤Ë¤ÏÊÑ´¹¤Ï½é´ü¾õÂÖ¤Ç½ª¤ê¡¢½ªÃ¼¤Î \(aq\\0\(aq ¥Ð¥¤¥È¤ò½ü¤¤¤Æ
  72 \fIdest\fP ¤Ë½ñ¤¹þ¤Þ¤ì¤¿¥Ð¥¤¥È¿ô¤òÊÖ¤¹¡£
  73 .PP
  74 .\"O The programmer must ensure that there is room for at least \fIn\fP bytes
  75 .\"O at \fIdest\fP.
  76 ¥×¥í¥°¥é¥Þ¡¼¤Ï \fIdest\fP ¤ËºÇÄã¤Ç¤â \fIn\fP ¥Ð¥¤¥È¤Î¶õ¤¤¬¤¢¤ë¤³¤È¤ò
  77 ÊÝ¾Ú¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
  78 .PP
  79 .\"O If \fIdest\fP is NULL, \fIn\fP is ignored, and the conversion proceeds as
  80 .\"O above, except that the converted bytes are not written out to memory,
  81 .\"O and that no length limit exists.
  82 \fIdest\fP ¤¬ NULL ¤Î¾ì¹ç¡¢\fIn\fP ¤ÏÌµ»ë¤µ¤ì¤ë¡£¾åµ¤ÈÆ±ÍÍ¤ËÊÑ´¹¤¬¹Ô
  83 ¤Ê¤ï¤ì¤ë¤¬ÊÑ´¹·ë²Ì¤Î¥Ð¥¤¥ÈÎó¤Ï¥á¥â¥ê¤Ë¤Ï½ñ¤¹þ¤Þ¤ì¤Ê¤¤¡£
  84 ¤Þ¤¿Ä¹¤µ¤Î¾å¸Â¤¬Â¸ºß¤·¤Ê¤¤¡£
  85 .PP
  86 .\"O In order to avoid the case 2 above, the programmer should make sure \fIn\fP
  87 .\"O is greater or equal to \fIwcstombs(NULL,src,0)+1\fP.
  88 ¾åµ¤Î 2. ¤Î¾ì¹ç¤òÈò¤±¤ë¤¿¤á¤Ë¡¢¥×¥í¥°¥é¥Þ¡¼¤Ï \fIn\fP ¤¬
  89 \fIwcstombs(NULL,src,0)+1\fP °Ê¾å¤Ç¤¢¤ë¤³¤È¤òÊÝ¾Ú¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
  90 .\"O .SH "RETURN VALUE"
  91 .SH ÊÖ¤êÃÍ
  92 .\"O The
  93 .\"O .BR wcstombs ()
  94 .\"O function returns the number of bytes that make up the
  95 .\"O converted part of multibyte sequence, not including the terminating null byte.
  96 .\"O If a wide character was encountered which could not be
  97 .\"O converted,
  98 .\"O .I (size_t)\ \-1
  99 .\"O is returned.
 100 .BR wcstombs ()
 101 ´Ø¿ô¤ÏÀ¸À®¤·¤¿¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤Î¥Ð¥¤¥È¿ô¤òÊÖ¤¹¡£½ªÃ¼¤Î
 102 ¥Ê¥ëÊ¸»ú¤Ï´Þ¤Þ¤Ê¤¤¡£¤â¤·ÊÑ´¹¤Ç¤¤Ê¤¤¥ï¥¤¥ÉÊ¸»ú¤ËÁø¶ø¤·¤¿¾ì¹ç¤Ë¤Ï
 103 .I (size_t)\ \-1
 104 ¤òÊÖ¤¹¡£
 105 .\"O .SH "CONFORMING TO"
 106 .SH ½àµò
 107 C99.
 108 .\"O .SH NOTES
 109 .SH Ãí°Õ
 110 .\"O The behavior of
 111 .\"O .BR wcstombs ()
 112 .\"O depends on the
 113 .\"O .B LC_CTYPE
 114 .\"O category of the
 115 .\"O current locale.
 116 .BR wcstombs ()
 117 ¤ÎÆ°ºî¤Ï¸½ºß¤Î¥í¥±¡¼¥ë¤Î
 118 .B LC_CTYPE
 119 ¥«¥Æ¥´¥ê¤Ë°ÍÂ¸¤·¤Æ¤¤¤ë¡£
 120 .PP
 121 .\"O The function
 122 .\"O .BR wcsrtombs ()
 123 .\"O provides a thread safe interface to
 124 .\"O the same functionality.
 125 .BR wcsrtombs ()
 126 ´Ø¿ô¤ÏÆ±¤¸µ¡Ç½¤Î¤¿¤á¤Î¥¹¥ì¥Ã¥É¡¦¥»¡¼¥Õ¤Ê
 127 ¥¤¥ó¥¿¡¼¥Õ¥§¡¼¥¹¤òÄó¶¡¤¹¤ë¡£
 128 .\"O .SH "SEE ALSO"
 129 .SH ´ØÏ¢¹àÌÜ
 130 .BR wcsrtombs (3)