[linuxjm/LDP_man-pages.git] / draft / man3 / mbsrtowcs.3

.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" References consulted:
.\"   GNU glibc-2 source code and manual
.\"   Dinkumware C library reference http://www.dinkumware.com/
.\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
.\"   ISO/IEC 9899:1999
.\"
.\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
.\"         all rights reserved.
.\" Translated Tue Jan 11 00:56:08 JST 2000
.\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\"
.TH MBSRTOWCS 3 1999-07-25 "GNU" "Linux Programmer's Manual"
.\"O .SH NAME
.SH ̾Á°
.\"O mbsrtowcs \- convert a multibyte string to a wide-character string
mbsrtowcs \- ¥Þ¥ë¥Á¥Ð¥¤¥Èʸ»úÎó¤ò¥ï¥¤¥Éʸ»úÎó¤ËÊÑ´¹¤¹¤ë
.\"O .SH SYNOPSIS
.SH ½ñ¼°
.nf
.B #include <wchar.h>
.sp
.BI "size_t mbsrtowcs(wchar_t *" dest ", const char **" src ,
.BI "                  size_t " len ", mbstate_t *" ps );
.fi
.\"O .SH DESCRIPTION
.SH ÀâÌÀ
.\"O If \fIdest\fP is not a NULL pointer, the
.\"O .BR mbsrtowcs ()
.\"O function converts the
.\"O multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP.
.\"O At most \fIlen\fP wide characters are written to \fIdest\fP.
.\"O The shift state
.\"O \fI*ps\fP is updated.
.\"O The conversion is effectively performed by repeatedly
.\"O calling
.\"O .I "mbrtowc(dest, *src, n, ps)"
.\"O where \fIn\fP is some
.\"O positive number, as long as this call succeeds, and then incrementing
.\"O \fIdest\fP by one and \fI*src\fP by the number of bytes consumed.
.\"O The conversion can stop for three reasons:
\fIdest\fP ¤¬ NULL ¥Ý¥¤¥ó¥¿¡¼¤Ç¤Ê¤±¤ì¤Ð¡¢
.BR mbsrtowcs ()
´Ø¿ô¤Ï
¥Þ¥ë¥Á¥Ð¥¤¥Èʸ»úÎó \fI*src\fP ¤ò \fIdest\fP ¤«¤é»Ï¤Þ¤ë¥ï¥¤¥Éʸ»úÎó¤Ë
ÊÑ´¹¤¹¤ë¡£\fIdest\fP ¤Ë¤ÏºÇÂç¤Ç \fIlen\fP ʸ»ú¤Î¥ï¥¤¥Éʸ»ú¤¬
½ñ¤­¹þ¤Þ¤ì¤ë¡£Æ±»þ¤Ë¥·¥Õ¥È¾õÂÖ \fI*ps\fP ¤ò¹¹¿·¤¹¤ë¡£
ÊÑ´¹¤Ï
.I "mbrtowc(dest, *src, n, ps)"
¤ò¡¢¤³¤Î¸Æ¤Ó½Ð¤·¤¬À®¸ù¤¹¤ë¸Â¤ê·«¤êÊÖ¤·¼Â¹Ô¤·¤¿¤Î¤È¼Â¼ÁŪ¤ËƱÍͤǤ¢¤ë¡£
¤³¤³¤Ç \fIn\fP ¤ÏÀµ¤Î¿ô¤Ç¤¢¤ê¡¢·«¤êÊÖ¤·¤´¤È¤Ë \fIdest\fP ¤¬ 1 Áý²Ã¤µ¤»¤é¤ì¡¢
\fI*src\fP ¤¬¾ÃÈñ¤·¤¿¥Ð¥¤¥È¿ô¤À¤±Áý²Ã¤µ¤»¤é¤ì¤ë¡£ÊÑ´¹¤Ï°Ê²¼¤Î»°¤Ä¤Î
¤¤¤º¤ì¤«¤Î¾ò·ï¤ÇÄä»ß¤¹¤ë:
.IP 1. 3
.\"O An invalid multibyte sequence has been encountered.
.\"O In this case \fI*src\fP
.\"O is left pointing to the invalid multibyte sequence,
.\"O .I (size_t)\ \-1
.\"O is returned,
.\"O and \fIerrno\fP is set to \fBEILSEQ\fP.
ÉÔÀµ¤Ê¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ËÁø¶ø¤·¤¿¡£¤³¤Î¾ì¹ç¤Ë¤Ï \fI*src\fP ¤ÏÉÔÀµ¤Ê
¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ò»Ø¤¹¤è¤¦¤Ë¤·¤Æ¡¢
.I (size_t)\ \-1
¤òÊÖ¤·¡¢\fIerrno\fP ¤Ë \fBEILSEQ\fP ¤òÀßÄꤹ¤ë¡£
.IP 2.
.\"O \fIlen\fP non-L\(aq\\0\(aq wide characters have been stored at \fIdest\fP.
.\"O In this
.\"O case \fI*src\fP is left pointing to the next
.\"O multibyte sequence to be converted,
.\"O and the number of wide characters written to \fIdest\fP is returned.
\fIlen\fP ʸ»ú¤Î L\(aq\\0\(aq °Ê³°¤Î¥ï¥¤¥Éʸ»ú¤ò \fIdest\fP ¤Ë³ÊǼ¤·¤¿¾ì¹ç¡£
¤³¤Î¾ì¹ç¤Ï \fI*src\fP ¤Ï¼¡¤ËÊÑ´¹¤µ¤ì¤ë¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ò»Ø¤¹¤è¤¦¤Ë¤·¤Æ¡¢
\fIdest\fP ¤Ë½ñ¤­¹þ¤Þ¤ì¤¿¥ï¥¤¥Éʸ»ú¤Î¿ô¤òÊÖ¤¹¡£
.IP 3.
.\"O The multibyte string has been completely converted, including the
.\"O terminating \(aq\\0\(aq (which has the side
.\"O effect of bringing back \fI*ps\fP to the
.\"O initial state).
.\"O In this case \fI*src\fP is set to NULL, and the number of wide
.\"O characters written to \fIdest\fP,
.\"O excluding the terminating L\(aq\\0\(aq character, is returned.
¥Þ¥ë¥Á¥Ð¥¤¥Èʸ»úÎ󤬽ªÃ¼¤Î \(aq\\0\(aq ¤Þ¤Ç´Þ¤á¤Æ´°Á´¤ËÊÑ´¹¤µ¤ì¤¿¾ì¹ç¡£
(¤³¤Î»þ¡¢ÉûºîÍѤȤ·¤Æ \fI*ps\fP ¤¬½é´ü¾õÂÖ¤ËÌᤵ¤ì¤ë¡£)
¤³¤Î¾ì¹ç¤Ï \fI*src\fP ¤Ë¤Ï NULL ¤¬ÀßÄꤵ¤ì¡¢½ªÃ¼¤Î L\(aq\\0\(aq ʸ»ú¤ò½ü¤¤¤Æ
\fIdest\fP ¤Ë½ñ¤­¹þ¤Þ¤ì¤¿Ê¸»ú¿ô¤òÊÖ¤¹¡£
.PP
.\"O If \fIdest\fP is NULL, \fIlen\fP is ignored,
.\"O and the conversion proceeds as above,
.\"O except that the converted wide characters are not written out to memory,
.\"O and that no length limit exists.
\fIdest\fP ¤¬ NULL ¤Î¾ì¹ç¡¢\fIlen\fP ¤Ï̵»ë¤µ¤ì¡¢¾åµ­¤ÈƱÍͤÎÊÑ´¹¤¬
¹Ô¤ï¤ì¤ë¤¬¡¢ÊÑ´¹¤µ¤ì¤¿¥ï¥¤¥Éʸ»ú¤Ï¥á¥â¥ê¤Ë½ñ¤­¹þ¤Þ¤ì¤º¡¢ÊÑ´¹Àè¤Î¾å¸Â
¤¬Â¸ºß¤·¤Ê¤¤¡£
.PP
.\"O In both of the above cases,
.\"O if \fIps\fP is a NULL pointer, a static anonymous
.\"O state only known to the
.\"O .BR mbsrtowcs ()
.\"O function is used instead.
¾åµ­¤Î¤É¤Á¤é¤Î¾ì¹ç¤Ç¤â¡¢\fIps\fP ¤¬ NULL ¥Ý¥¤¥ó¥¿¡¼¤Ê¤é¤Ð¡¢
Âå¤ê¤Ë
.BR mbsrtowcs ()
´Ø¿ô¤Î¤ß¤¬»ÈÍѤ¹¤ëÀÅŪ¤Ç̾Á°¤Î¤Ê¤¤¾õÂÖ¤¬»ÈÍѤµ¤ì¤ë¡£
.PP
.\"O The programmer must ensure that there is room for at least \fIlen\fP wide
.\"O characters at \fIdest\fP.
¥×¥í¥°¥é¥Þ¡¼¤Ï \fIdest\fP ¤ËºÇÄã¤Ç¤â \fIlen\fP ¥ï¥¤¥Éʸ»ú¤ò½ñ¤­¹þ¤à¤³
¤È¤¬¤Ç¤­¤ë¶õ´Ö¤¬¤¢¤ë¤³¤È¤òÊݾڤ·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
.\"O .SH "RETURN VALUE"
.SH ÊÖ¤êÃÍ
.\"O The
.\"O .BR mbsrtowcs ()
.\"O function returns the number of wide characters that make
.\"O up the converted part of the wide-character string, not including the
.\"O terminating null wide character.
.\"O If an invalid multibyte sequence was
.\"O encountered,
.\"O .I (size_t)\ \-1
.\"O is returned, and \fIerrno\fP set to \fBEILSEQ\fP.
.BR mbsrtowcs ()
´Ø¿ô¤Ï¥ï¥¤¥Éʸ»úÎó¤ËÊÑ´¹´°Î»¤·¤¿¥ï¥¤¥Éʸ»ú¤Î¿ô¤òÊÖ¤¹¡£
½ªÃ¼¤Î¥Ê¥ë¥ï¥¤¥Éʸ»ú¤Ï´Þ¤Þ¤Ê¤¤¡£ÉÔÀµ¤Ê¥Þ¥ë¥Á¥Ð¥¤¥ÈÎó¤ËÁø¶ø¤·¤¿¾ì¹ç¤Ë¤Ï
.I (size_t)\ \-1
¤òÊÖ¤·¡¢\fIerrno\fP ¤Ë \fBEILSEQ\fP ¤òÀßÄꤹ¤ë¡£
.\"O .SH "CONFORMING TO"
.SH ½àµò
C99.
.\"O .SH NOTES
.SH Ãí°Õ
.\"O The behavior of
.\"O .BR mbsrtowcs ()
.\"O depends on the
.\"O .B LC_CTYPE
.\"O category of the
.\"O current locale.
.BR mbsrtowcs ()
¤ÎÆ°ºî¤Ï¸½ºß¤Î¥í¥±¡¼¥ë¤Î
.B LC_CTYPE
¥«¥Æ¥´¥ê¤Ë°Í¸¤·¤Æ¤¤¤ë¡£
.PP
.\"O Passing NULL as \fIps\fP is not multithread safe.
\fIps\fP ¤È¤·¤Æ NULL ¤òÅϤ¹¤³¤È¤Ï¥Þ¥ë¥Á¥¹¥ì¥Ã¥É¤Ç¤Ï°ÂÁ´¤Ç¤Ê¤¤¡£
.\"O .SH "SEE ALSO"
.SH ´ØÏ¢¹àÌÜ
.BR iconv (3),
.BR mbsnrtowcs (3),
.BR mbstowcs (3)