draft/man3/mbtowc.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:56:02 JST 2000
  17 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  18 .\"
  19 .TH MBTOWC 3  2001-07-04 "GNU" "Linux Programmer's Manual"
  20 .\"O .SH NAME
  21 .SH Ì¾Á°
  22 .\"O mbtowc \- convert a multibyte sequence to a wide character
  23 mbtowc \- ¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ò¥ï¥¤¥ÉÊ¸»ú¤ËÊÑ´¹¤¹¤ë
  24 .\"O .SH SYNOPSIS
  25 .SH ½ñ¼°
  26 .nf
  27 .B #include <stdlib.h>
  28 .sp
  29 .BI "int mbtowc(wchar_t *" pwc ", const char *" s ", size_t " n );
  30 .fi
  31 .\"O .SH DESCRIPTION
  32 .SH ÀâÌÀ
  33 .\"O The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is
  34 .\"O not NULL.
  35 .\"O In this case, the
  36 .\"O .BR mbtowc ()
  37 .\"O function inspects at most \fIn\fP
  38 .\"O bytes of the multibyte string starting at \fIs\fP,
  39 .\"O extracts the next complete
  40 .\"O multibyte character, converts it to a wide character and stores it at
  41 .\"O \fI*pwc\fP.
  42 .\"O It updates an internal shift state only known to the mbtowc
  43 .\"O function.
  44 .\"O If \fIs\fP does not point to a \(aq\\0\(aq byte, it returns the number
  45 .\"O of bytes that were consumed from \fIs\fP, otherwise it returns 0.
  46 ¤³¤Î´Ø¿ô¤¬ÍÑ¤¤¤é¤ì¤ë¾ì¹ç¡¢ÄÌ¾ï \fIs\fP ¤¬ NULL ¤Ç¤Ê¤¯ \fIpwc\fP ¤â NULL
  47 ¤Ç¤Ê¤¤¡£¤³¤Î¾ì¹ç¤Ï
  48 .BR mbtowc ()
  49 ´Ø¿ô¤Ï \fIs\fP ¤«¤é»Ï¤Þ¤ë
  50 ºÇÂç \fIn\fP ¥Ð¥¤¥È¤Î¥Þ¥ë¥Á¥Ð¥¤¥ÈÊ¸»úÎó¤ò¸¡ºº¤·¤Æ¡¢¼¡¤Î´°Á´¤Ê¥Þ¥ë¥Á¥Ð¥¤¥È
  51 Ê¸»ú¤ò¼è¤ê½Ð¤·¡¢¤½¤ì¤ò¥ï¥¤¥ÉÊ¸»ú¤ËÊÑ´¹¤·¤Æ \fI*pwc\fP ¤Ë³ÊÇ¼¤¹¤ë¡£
  52 Æ±»þ¤Ë mbtowc ´Ø¿ô¤Î¤ß¤¬»ÈÍÑ¤¹¤ëÆâÉô¾õÂÖ¤ò¹¹¿·¤¹¤ë¡£\fIs\fP ¤¬ \(aq\\0\(aq
  53 °Ê³°¤Î¥Ð¥¤¥È¤ò»Ø¤·¤Æ¤¤¤ë¾ì¹ç¤Ï¡¢\fIs\fP ¤«¤é¾ÃÈñ¤¹¤ë¥Ð¥¤¥È¿ô¤òÊÖ¤¹¡£
  54 \fIs\fP ¤¬ \(aq\\0\(aq ¤ò»Ø¤·¤Æ¤¤¤ë¾ì¹ç¤Ë¤Ï 0 ¤òÊÖ¤¹¡£
  55 .PP
  56 .\"O If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte
  57 .\"O character, or if they contain an invalid multibyte sequence,
  58 .\"O .BR mbtowc ()
  59 .\"O returns \-1.
  60 .\"O This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP,
  61 .\"O if the multibyte string contains redundant shift sequences.
  62 \fIs\fP ¤«¤é»Ï¤Þ¤ë \fIn\fP ¥Ð¥¤¥È¤¬´°Á´¤Ê¥Þ¥ë¥Á¥Ð¥¤¥ÈÊ¸»ú¤ò´Þ¤ó¤Ç
  63 ¤¤¤Ê¤¤¾ì¹ç¤äÉÔÀµ¤Ê¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ò´Þ¤ó¤Ç¤¤¤ë¾ì¹ç¤Ë¤Ï
  64 .BR mbtowc ()
  65 ¤Ï
  66 \-1 ¤òÊÖ¤¹¡£¥Þ¥ë¥Á¥Ð¥¤¥ÈÊ¸»úÎó¤Ë¾éÄ¹¤Ê¥·¥Õ¥È¥·¡¼¥±¥ó¥¹¤¬
  67 ´Þ¤Þ¤ì¤Æ¤¤¤ë¤È \fIn\fP >= \fIMB_CUR_MAX\fP ¤Î¾ì¹ç¤â¤³¤Î¤è¤¦¤Ê¤³¤È¤¬
  68 µ¯¤³¤ê¤¨¤ë¡£
  69 .PP
  70 .\"O A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL.
  71 .\"O In this
  72 .\"O case the
  73 .\"O .BR mbtowc ()
  74 .\"O function behaves as above, except that it does not
  75 .\"O store the converted wide character in memory.
  76 \fIs\fP ¤¬ NULL ¤Ç¤Ê¤¯ \fIpwc\fP ¤¬ NULL ¤Î¾ì¹ç¤Ï
  77 .BR mbtowc ()
  78 ´Ø¿ô¤Ï
  79 ¾åµ¤ÈÆ±ÍÍ¤ËÆ°ºî¤¹¤ë¤¬¡¢ÊÑ´¹¤·¤¿¥ï¥¤¥ÉÊ¸»ú¤Ï¥á¥â¥ê¤Ë¤Ï½ñ¤¹þ¤Þ¤ì¤Ê¤¤¡£
  80 .PP
  81 .\"O A third case is when \fIs\fP is NULL.
  82 .\"O In this case, \fIpwc\fP and \fIn\fP are
  83 .\"O ignored.
  84 .\"O The
  85 .\"O .BR mbtowc ()
  86 .\"O function
  87 .\" The Dinkumware doc and the Single UNIX specification say this, but
  88 .\" glibc doesn't implement this.
  89 .\"O resets the shift state, only known to this function,
  90 .\"O to the initial state, and
  91 .\"O returns nonzero if the encoding has nontrivial shift state, or zero if the
  92 .\"O encoding is stateless.
  93 »°ÈÖÌÜ¤Î¾ì¹ç¤È¤·¤Æ \fIs\fP ¤¬ NULL ¤Î¾ì¹ç¤Ï \fIpwc\fP ¤È \fIn\fP ¤Ï
  94 Ìµ»ë¤µ¤ì¤ë¡£
  95 .BR mbtowc ()
  96 ´Ø¿ô¤Î¤ß¤¬»ÈÍÑ¤¹¤ë¥·¥Õ¥È¾õÂÖ¤Ï½é´ü¾õÂÖ¤Ë
  97 Ìá¤µ¤ì¤ë¡£¤½¤·¤ÆÊ¸»úÉä¹æ¤¬¥·¥Õ¥È¾õÂÖ¤Ë°ÍÂ¸¤¹¤ë¤Ê¤é¤Ð¥¼¥í°Ê³°¤ò¡¢Ê¸»úÉä¹æ¤¬
  98 ¾õÂÖ¤Ë¤è¤é¤Ê¤¤¤Ê¤é¤Ð¥¼¥í¤òÊÖ¤¹¡£
  99 .\"O .SH "RETURN VALUE"
 100 .SH ÊÖ¤êÃÍ
 101 .\"O If \fIs\fP is not NULL, the
 102 .\"O .BR mbtowc ()
 103 .\"O function returns the number of
 104 .\"O consumed bytes starting at \fIs\fP, or 0 if \fIs\fP points to a null byte,
 105 .\"O or \-1 upon failure.
 106 \fIs\fP ¤¬ NULL ¤Ç¤Ê¤±¤ì¤Ð
 107 .BR mbtowc ()
 108 ´Ø¿ô¤Ï \fIs\fP ¤«¤é¾ÃÈñ¤·¤¿
 109 ¥Ð¥¤¥È¿ô¤ò¡¢\fIs\fP ¤¬¥Ê¥ëÊ¸»ú¤ò»Ø¤·¤Æ¤¤¤ë¾ì¹ç¤Ï¥¼¥í¤ò¡¢
 110 ÊÑ´¹¤Ë¼ºÇÔ¤·¤¿¾ì¹ç¤Ï \-1 ¤òÊÖ¤¹¡£
 111 .PP
 112 .\"O If \fIs\fP is NULL, the
 113 .\"O .BR mbtowc ()
 114 .\"O function
 115 .\"O returns nonzero if the encoding
 116 .\"O has nontrivial shift state, or zero if the encoding is stateless.
 117 \fIs\fP ¤¬ NULL ¤Ê¤é¤Ð
 118 .BR mbtowc ()
 119 ´Ø¿ô¤ÏÊ¸»úÉä¹æ¤¬¥·¥Õ¥È¾õÂÖ¤Ë°ÍÂ¸
 120 ¤·¤Æ¤¤¤ì¤Ð¥¼¥í°Ê³°¤ò¡¢¾õÂÖ¤Ë¤è¤é¤Ê¤±¤ì¤Ð¥¼¥í¤òÊÖ¤¹¡£
 121 .\"O .SH "CONFORMING TO"
 122 .SH ½àµò
 123 C99.
 124 .\"O .SH NOTES
 125 .SH Ãí°Õ
 126 .\"O The behavior of
 127 .\"O .BR mbtowc ()
 128 .\"O depends on the
 129 .\"O .B LC_CTYPE
 130 .\"O category of the
 131 .\"O current locale.
 132 .BR mbtowc ()
 133 ¤ÎÆ°ºî¤Ï¸½ºß¤Î¥í¥±¡¼¥ë¤Î
 134 .B LC_CTYPE
 135 ¥«¥Æ¥´¥ê¤Ë°ÍÂ¸¤·¤Æ¤¤¤ë¡£
 136 .PP
 137 .\"O This function is not multithread safe.
 138 .\"O The function
 139 .\"O .BR mbrtowc (3)
 140 .\"O provides
 141 .\"O a better interface to the same functionality.
 142 ¤³¤Î´Ø¿ô¤Ï¥Þ¥ë¥Á¥¹¥ì¥Ã¥É¤Ç¤Ï°ÂÁ´¤Ç¤Ï¤Ê¤¤¡£
 143 .BR mbrtowc (3)
 144 ´Ø¿ô¤Ï
 145 Æ±¤¸µ¡Ç½¤Î¤è¤êÎÉ¤¤¥¤¥ó¥¿¡¼¥Õ¥§¡¼¥¹¤òÄó¶¡¤¹¤ë¡£
 146 .\"O .SH "SEE ALSO"
 147 .SH ´ØÏ¢¹àÌÜ
 148 .BR MB_CUR_MAX (3),
 149 .BR mbrtowc (3),
 150 .BR mbstowcs (3)