.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Paul Borman at Krystal Technologies.
.\"
.\" 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.
.\"
.\"	@(#)rune.3	8.2 (Berkeley) 12/11/93
.\" %FreeBSD: src/lib/libc/locale/rune.3,v 1.10.2.6 2001/12/14 18:33:54 ru Exp %
.\"
.\" $FreeBSD$
.Dd December 11, 1993
.Dt RUNE 3
.Os
.Sh 名称
.Nm setrunelocale ,
.Nm setinvalidrune ,
.Nm sgetrune ,
.Nm sputrune ,
.Nm fgetrune ,
.Nm fungetrune ,
.Nm fputrune
.Nd C 用ルーンサポート
.Sh ライブラリ
.Lb libc
.Sh 書式
.In rune.h
.In errno.h
.Ft int
.Fn setrunelocale "char *locale"
.Ft void
.Fn setinvalidrune "rune_t rune"
.Ft rune_t
.Fn sgetrune "const char *string" "size_t n" "char const **result"
.Ft int
.Fn sputrune "rune_t rune" "char *string" "size_t n" "char **result"
.Pp
.In stdio.h
.Ft long
.Fn fgetrune "FILE *stream"
.Ft int
.Fn fungetrune "rune_t rune" "FILE *stream"
.Ft int
.Fn fputrune "rune_t rune" "FILE *stream"
.Sh 解説
.Fn setrunelocale
は、マルチバイトストリングとしてルーンを表現するための
エンコードのタイプ、および
.Aq Pa ctype.h
で定義されたルーンのプロパティを制御します。
.Fa locale
引数は、ロードするロケールを指定します。
ロケールが正常にロードされると
.Dv 0
が戻され、ロードで問題が生じるとエラータイプを表す
errno
値が戻されます。
.Pp
.Fn setinvalidrune
関数は、グローバル値
.Dv _INVALID_RUNE
の値を
.Fa rune
に設定します。
.Pp
.Fn sgetrune
関数は、長さが最大
.Fa n
バイトの
1
つのマルチバイトキャラクタを
.Fa string
から読み込もうとします。
.Fn sgetrune
で問題が発生しなかった場合はルーンが戻されます。
.Fa result
が
.Dv NULL
ではない場合、
.Fa *result
は、
.Fa string
で変換されなかった最初のバイトを指します。
.Fa string
の最初の
.Fa n
バイトが完全なマルチバイトキャラクタを表さない場合は
.Dv _INVALID_RUNE
が戻され、
.Fa *result
は
.Fa string
を指します。
.Fa string
の最初でエンコードのエラーが発生した場合は
.Dv _INVALID_RUNE
が戻され、
.Fa *result
は
.Fa string
の第
2
キャラクタを指します。
.Pp
.Fn sputrune
関数は、マルチバイトストリングとして
.Fa rune
をエンコードし、
.Fa string
に保存しようとします。しかし
.Fa n
バイトまでしか保存されません。
.Fa result
が
.Dv NULL
ではない場合、
.Fa *result
は、新しいマルチバイトキャラクタに続くストリングの
最初のバイトを指すように設定されます。
.Fa string
が
.Dv NULL
である場合、
.Fa *result
は
.Dv "(char *)0 +"
.Fa x
を指します。
.Fa x
は、マルチバイト値の保存に必要なバイト数です。
マルチバイトキャラクタが
.Fa n
より長いバイトから構成され、
.Fa result
が
.Dv NULL
ではない場合、
.Fa *result
は
.Dv NULL
に設定されます。
どのような場合でも、
.Fn sputrune
は、マルチバイトキャラクタとして
.Fa rune
を保存するために必要なバイト数を戻します。
.Pp
.Fn fgetrune
関数は、
1
つのルーンをデコードするのに足る数のバイトを
.Fa stream
から読み込もうとすることを除けば、
.Fn sgetrune
と同じ動作をします。ファイルの終わりに達した場合は
.Dv EOF
を、エンコードでエラーが発生した場合は
.Dv _INVALID_RUNE
を、問題が発生しなかった場合はデコードされたルーンを戻します。
.Pp
.Fn fungetrune
関数は、次に
.Fn fgetrune
を呼び出した場合に
.Fa rune
が戻されるように、
.Fn sputrune
が与える
.Fa rune
のマルチバイトエンコードを
.Fa stream
にプッシュします。エラーが発生した場合は
.Dv EOF
を戻し、エラーが発生しなかった場合は
.Dv 0
を戻します。
.Pp
.Fn fputrune
関数は、
.Fn sputrune
が与える
.Fa rune
のマルチバイトエンコードを
.Fa stream
に書き込みます。エラーが発生した場合は
.Dv EOF
を戻し、エラーが発生しなかった場合は
.Dv 0
を戻します。
.Sh 戻り値
.Fn setrunelocale
関数は、以下の値のどれか
1
つを戻します。
.Bl -tag -width Er
.It Er 0
.Fn setrunelocale
で問題が発生しませんでした。
.It Bq Er EFAULT
.Fa locale
が
.Dv NULL
になっています。
.It Bq Er ENOENT
ロケールが見つかりません。
.It Bq Er EFTYPE
見つかったファイルが正しいファイルではありません。
.It Bq Er EINVAL
ロケールで示されるエンコードが未知のものです。
.El
.Pp
.Fn sgetrune
関数は、読み込んだルーンか
.Dv _INVALID_RUNE
を戻します。
.Fn sputrune
関数は、マルチバイトストリングとして
.Fa rune
を保存するために必要なバイト数を戻します。
.Sh 関連ファイル
.Bl -tag -width /usr/share/locale/locale/LC_CTYPE -compact
.It Pa $PATH_LOCALE/ Ns Em locale Ns /LC_CTYPE
.It Pa /usr/share/locale/ Ns Em locale Ns /LC_CTYPE
ロケール
.Em locale
のバイナリ
LC_CTYPE
ファイル
.El
.Sh 関連項目
.Xr mbrune 3 ,
.Xr setlocale 3 ,
.Xr euc 4 ,
.Xr utf2 4
.Sh 注
ANSI C
の
.Em wchar_t
型は、
.Em rune_t
と同じです。美しさに劣る
ANSI C
プリミティブをシステムの土台としない故意の選択であることを強調するために
.Em rune_t
が選ばれました。
.Sh 歴史
この関数は、
.Bx 4.4
で初めて登場しました。
.Pp
.Fn setrunelocale
関数とその他の非
ANSI
ルーン関数は、
ANSI
マルチバイトとワイドキャラクタサポートのより確実な代替案としての
.Sy Bell Labs の Plan 9
にヒントを得ました。
.\"They were conceived at the San Diego 1993 Summer USENIX conference by
.\"Paul Borman of Krystal Technologies, Keith Bostic of CSRG and Andrew Hume
.\"of Bell Labs.
.Pp
すべての
ANSI
マルチバイトとワイドキャラクタのサポート関数は、
ルーン関数を使用して作成されています。