.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Donn Seeley of BSDI.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)multibyte.3	8.1 (Berkeley) 6/4/93
.\" %FreeBSD: src/lib/libc/locale/multibyte.3,v 1.6.2.5 2001/12/14 18:33:54 ru Exp %
.\" $FreeBSD$
.\"
.Dd June 4, 1993
.Dt MULTIBYTE 3
.Os
.Sh 名称
.Nm mblen ,
.Nm mbstowcs ,
.Nm mbtowc ,
.Nm wcstombs ,
.Nm wctomb
.Nd C 言語のマルチバイト文字サポート
.Sh ライブラリ
.Lb libc
.Sh 書式
.In stdlib.h
.Ft int
.Fn mblen "const char *mbchar" "size_t nbytes"
.Ft size_t
.Fn mbstowcs "wchar_t *wcstring" "const char *mbstring" "size_t nwchars"
.Ft int
.Fn mbtowc "wchar_t *wcharp" "const char *mbchar" "size_t nbytes"
.Ft size_t
.Fn wcstombs "char *mbstring" "const wchar_t *wcstring" "size_t nbytes"
.Ft int
.Fn wctomb "char *mbchar" "wchar_t wchar"
.Sh 解説
中国語のような自然言語の基本要素は、C 言語の
.Va char Ns s
型ひとつでは一意に表現できません。
標準 C 言語規格では、
.Em ワイド
文字と
.Em マルチバイト
文字という、自然言語のエンコード方法の拡張を扱う 2 つの異なる方法がサポートされています。
ワイド文字は、基本要素ひとつひとつを
.Va wchar_t
型の単一オブジェクトへマップできるような内部表現です。
マルチバイト文字は入出力に使用され、C 言語の
.Va char Ns s
型の並びとして基本要素ひとつひとつをコード化します。
マルチバイト文字では、個々の基本要素は 1 バイトまたはそれ以上(最大
.Dv MB_CHAR_MAX
バイト ) にマップされます。
.Pp
現在のロケール
.Pq Xr setlocale 3
によりワイド文字とマルチバイト文字のどちらで解釈するかが決定されます。
ロケールカテゴリ
.Dv LC_CTYPE
の指定によりこの解釈を制御します。
型
.Va wchar_t
は、ワイド文字を表現するにあたり、すべてのロケールに対して最大の値を収容できるだけの十分な大きさを持ちます。
.Pp
マルチバイト文字列には、与えられた表現中で規定されるモード間の切り替えをするための
.Sq シフト
指示子が含まれることがあります。
明示的にシフトの発生を表すバイト列を使用すると、これらのバイトは別々の文字とはみなされずに、それと隣接する文字と一緒にまとめられます。
.Sq 初期
シフト状態は区別されて、常に存在しています。
関数
.Fn mbstowcs
と
.Fn wcstombs
は、マルチバイト文字列が初期シフト状態から始まって解釈されると仮定します。
関数
.Fn mblen ,
.Fn mbtowc ,
.Fn wctomb
は、内部で静的にシフト状態を維持管理します。
ポインタ
.Fa mbchar
がヌルである呼び出しでは、現在のロケールがシフト状態を必要とする場合は 0 以外が戻されます。シフト状態を必要としない場合は 0 が戻されます。
シフト状態を必要とする場合、シフト状態は初期状態にリセットされます。
.Dv LC_CTYPE
か
.Dv LC_ALL
カテゴリを指定して
.Fn setlocale
を呼び出した後では、内部シフト状態は未定義になります。
.Pp
処理に便利なように、値が 0 のワイド文字
(ヌルワイド文字)
は、ワイド文字列の終了として認識されます。
値が 0 の文字
(ヌルバイト)
は、マルチバイト文字列の終了として認識されます。
マルチバイト文字では、ヌルバイト列は許可されていません。
.Pp
関数
.Fn mblen
は、マルチバイト文字
.Fa mbchar
のバイト長を算出します。
.Fa nbytes
までが検査されます。
.Pp
関数
.Fn mbtowc
はマルチバイト文字
.Fa mbchar
をワイド文字に変換し、その結果を
.Fa wcharp
が指すオブジェクトに格納します。
.Fa nbytes
バイトまでが検査されます。
.Pp
関数
.Fn wctomb
はワイド文字
.Fa wchar
をマルチバイト文字に変換し、その結果を
.Fa mbchar
に格納します。
.Fa mbchar
が指すオブジェクトは、マルチバイト文字を収容できるだけの大きさを持たねばなりません。
.Pp
関数
.Fn mbstowcs
は、マルチバイト文字列
.Fa mbstring
をワイド文字列
.Fa wcstring .
に変換します。
.Fa nwchars
の大きさのワイド文字までしか格納されません。
終了を示すヌルワイド文字は、空きがある場合に付加されます。
.Pp
関数
.Fn wcstombs
は、ワイド文字列
.Fa wcstring
をマルチバイト文字列
.Fa mbstring
に変換します。
.Fa nbytes
バイトまでが
.Fa mbstring
に格納されます。
文字列の最後の断片的なマルチバイト文字は格納されません。マルチバイト文字列は、空きがあればヌルで終わります。
.Sh "戻り値
現在のロケールでマルチバイト文字がサポートされていない場合、これらすべての関数は、文字を処理できる場合は \-1 を返し、処理できない場合は 0 を返します。
.Pp
.Fa mbchar
が
.Dv NULL
である場合、関数
.Fn mblen ,
.Fn mbtowc ,
.Fn wctomb
は、シフト状態がサポートされている場合は 0 以外を返し、シフト状態がサポートされていない場合は 0 を返します。
.Fa mbchar
が有効であると、これらの関数は
.Fa mbchar
で処理されたバイト数を返します。マルチバイト文字を認識できない場合か変換できない場合は \-1 を返します。
.Pp
関数
.Fn mbstowcs
は、変換されたワイド文字の数を返します。終了を示すヌルワイド文字は数に含めません。
関数
.Fn wcstombs
は、変換されたバイト数を返します。終了を示すヌルバイトは数に含めません。
不正なマルチバイト文字があると、どちらの関数も \-1 を返します。
.Sh "関連項目
.Xr mbrune 3 ,
.Xr rune 3 ,
.Xr setlocale 3 ,
.Xr euc 4 ,
.Xr utf2 4
.Sh 規格
関数
.Fn mblen ,
.Fn mbstowcs ,
.Fn mbtowc ,
.Fn wcstombs
.Fn wctomb
は
.St -isoC
に準拠しています。
.Sh バグ
現在のシステムは、シフト状態をサポートしません。