.\" Copyright (c) 1989, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" 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.
.\"
.\"     @(#)unvis.3	8.2 (Berkeley) 12/11/93
.\" %FreeBSD: src/lib/libc/gen/unvis.3,v 1.6.2.5 2001/12/14 18:33:51 ru Exp %
.\" $FreeBSD$
.\"
.Dd December 11, 1993
.Dt UNVIS 3
.Os
.Sh 名称
.Nm unvis ,
.Nm strunvis
.Nd キャラクタの画像表現のデコード
.Sh ライブラリ
.Lb libc
.Sh 書式
.In vis.h
.Ft int
.Fn unvis "char *cp" "int c" "int *astate" "int flag"
.Ft int
.Fn strunvis "char *dst" "const char *src"
.Sh 解説
.Fn unvis
および
.Fn strunvis
関数は、例えば
.Xr vis 3
関数によって作り
出されたようなキャラクタの画像表現をデコードして元の形に戻します。
unvisは
.Ar c
にある連続するキャラクタとともに有効なシーケンスが認識されるまで呼び
出され、それが認識されるとデコードされたキャラクタが
.Ar cp
によって指されるキャラクタのところに置かれます。
strunvisは、
.Ar src
により指されるキャラクタを
.Ar dst
により指されるバッファへデコードします。
.Pp
.Fn strunvis
関数は、エスケープシーケンスをデコードしながら単に
.Ar src
を
.Ar dst
へコピーし、
.Ar dst
に置かれたキャラクタの数を返すか、または無効な
エスケープシーケンスが検出された場合には \-1 を返します。
.Ar dst
のサイズは、
.Ar src
のサイズに等しくなければなりません (すなわち、デコード中には拡張は
起こりません)。
.Pp
.Fn unvis
関数は、任意のバイトストリームをデコードできるステートマシンを
インプリメントしています。デコードされるそのバイトに付随するすべての
ステートは、
.Fn unvis
関数の外に保存されますから (すなわち、ステートへの
ポインタは渡されますから)、異なるストリームをデコードする呼び出しを自由に
混在することができます。バイトストリームのデコードを開始するには、まず
整数をゼロに初期化します。この整数へのポインタおよびデコード先キャラクタ
へのポインタとともに連続するバイトのそれぞれに
.Fn unvis
を呼び出します。
.Fn unvis
関数は、適切に取扱わねばならないいくつかのリターンコードを
持っています。それらは次の通りです:
.Bl -tag -width UNVIS_VALIDPUSH
.It Li \&0 (ゼロ)
キャラクタがもう一つ必要であり、まだ何も認識されていません。
.It Dv UNVIS_VALID
有効なキャラクタが認識され、cp によって指される場所に置かれています。
.It Dv UNVIS_VALIDPUSH
有効なキャラクタが認識され、cp によって指される場所に
置かれています。しかし、現在渡されているそのキャラクタをもう一度渡す
必要があります。
.It Dv UNVIS_NOCHAR
有効なシーケンスが検出されたが、キャラクタは
作成されていません。このリターンコードは、キャラクタの間の論理的区切りを
示すために必要です。
.It Dv UNVIS_SYNBAD
無効なエスケープシーケンスが検出されたか、または
デコーダが不明のステートにあります。デコーダはスタート時のステートに
置かれます。
.El
.Pp
ストリームのすべてのバイトが処理されたとき、
.Ar flag
を
.Dv UNVIS_END
に設定してもう一度
.Fn unvis
を呼び出して残っているキャラクタを
抽出します (渡されたキャラクタは無視されます)。
.Pp
次のような部分的コードは、
.Fn unvis
の適切な使用法を示しています。
.Bd -literal -offset indent
int state = 0;
char out;

while ((ch = getchar()) != EOF) {
again:
	switch(unvis(&out, ch, &state, 0)) {
	case 0:
	case UNVIS_NOCHAR:
		break;
	case UNVIS_VALID:
		(void) putchar(out);
		break;
	case UNVIS_VALIDPUSH:
		(void) putchar(out);
		goto again;
	case UNVIS_SYNBAD:
		(void)fprintf(stderr, "bad sequence!\en");
	exit(1);
	}
}
if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID)
	(void) putchar(out);
.Ed
.Sh 関連項目
.Xr vis 1
.Sh 歴史
.Fn unvis
関数は、
.Bx 4.4
ではじめて登場しました。