名称

unvis, strunvis — 文字の視覚表現をデコード (復号化) する

ライブラリ

Standard C Library (libc, -lc)

書式

#include < vis.h>

int
unvis( char *cp, int c, int *astate, int flag);

int
strunvis( char *dst, const char *src);

int
strnunvis( char *dst, size_t dlen, const char *src);

int
strunvisx( char *dst, const char *src, int flag);

int
strnunvisx( char *dst, size_t dlen, const char *src, int flag);

解説

unvis(), strunvis() と strunvisx() 関数は、元の形式に戻す vis(3) 関数によって生成されるような、文字の視覚表現をデコード (復号化) するために使用されます。

unvis() 関数は、デコードされた文字が、 cp によって指される文字で利用可能である時点で、有効なシーケンスが認識されるまで、 c の連続する文字で呼び出されます。

strunvis() 関数は、 src によって指される文字を dst によって指されるバッファへデコードします。 strunvis() 関数は、途中のあらゆるエスケープシーケンスをデコードして、 src を dst へ単にコピーし、 dst に入れられた文字の数を返すか、または無効のエスケープシーケンスが検出されたなら、-1 を返します。 dst のサイズは、 src のサイズと等しくなければなりません (すなわち、拡張は、デコードの間に起こりません)。

strunvisx() 関数は、 strunvis() 関数と同じように行いますが、利用者は、文字列 src がエンコード (符号化) されるスタイルを指定するフラグを追加することができます。現在、サポートされたフラグは、次の通りです: VIS_HTTPSTYLE と VIS_MIMESTYLE。

unvis() 関数は、任意のバイトのストリームをデコードするために使用することができる状態マシン (state machine) を実装しています。デコードされているバイトに関連するすべての状態は、 unvis() 関数の外側に格納される (すなわち、状態へのポインタが渡され) ので、異なるストリームをデコードする呼び出しを自由に混在することができます。バイトのストリームのデコードを開始するためには、最初に整数を 0 に初期化します。この整数へのポインタとあて先の文字へのポインタとともに、各連続するバイトで unvis() を呼び出します。 unvis() 関数には、適切に扱われなければならない、いくつかの返りコードがあります。それらは、次の通りです:

0 (ゼロ)

別の文字が必要です。まだ何も認識されていません。

UNVIS_VALID

有効な文字が認識されており、 cp によって指される場所で利用可能です。

UNVIS_VALIDPUSH

有効な文字が認識されており、 cp によって指される場所で利用可能です。しかしながら、現在渡された文字は、再び渡されるべきです。

UNVIS_NOCHAR

有効なシーケンスが検出されましたが、文字は、作成されませんでした。この返りコードは、文字の間の論理的な中断を示すために必要です。

UNVIS_SYNBAD

無効のエスケープシーケンスが検出されるか、またはデコーダが未知の状態です。デコーダは、開始している状態に置かれます。

ストリーム中のすべてのバイトが処理されたとき、あらゆる残っている文字を抽出するために、もう一度 UNVIS_END に設定されたフラグで unvis() を呼び出します (渡された文字は、無視されます)。

また flag 引数は、ソースのエンコード (符号化) スタイルを指定するために使用されます。 VIS_HTTPSTYLE または VIS_HTTP1808, に設定されるなら、 unvis() は、RFC 1808 で指定されるように URI 文字列をデコードします。 VIS_HTTP1866 に設定されるなら、 unvis() は、RFC 1866 で指定されるように実体の参照と番号文字の参照をデコードします。 VIS_MIMESTYLE に設定されるなら、 unvis() は、RFC 2045 で指定されるように MIME Quoted-Printable 文字列をデコードします。 VIS_NOESCAPE に設定されるなら、 unvis() は、‘ \’で引用された文字をデコードしません。

次のコードの破片は、 unvis() の適切な使用を説明しています。

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: 
  errx(EXIT_FAILURE, "Bad character sequence!"); 
 } 
} 
if (unvis(&out, '\0', &state, UNVIS_END) == UNVIS_VALID) 
 (void)putchar(out);

エラー

関数 strunvis(), strnunvis(), strunvisx() と strnunvisx() は、エラーで-1 を返し、 errno を次のように設定します:

[ EINVAL]

無効のエスケープシーケンスが検出されたか、またはデコーダが未知の状態です。

さらに、関数 strnunvis() と strnunvisx() は、またエラーで errno を次のように設定します:

[ ENOSPC]

変換を実行するための十分な空間がありません。

関連項目

unvis(1), vis(1), vis(3) R. Fielding, Relative Uniform Resource Locators, RFC1808.

歴史

unvis() 関数は、 4.4BSD ではじめて登場しました。 strnunvis() と strnunvisx() 関数は、 NetBSD 6.0 と FreeBSD 9.2 で登場しました。

バグ

名前 VIS_HTTP1808 と VIS_HTTP1866 は、間違っています。パーセントエンコーディング (符号化) は、URL のためのオリジナルの RFC である、 RFC 1738 定義されました。 RFC 1866 は、番号文字の参照と実体の参照の概念を継承する、 SGML のアプリケーション、HTML 2.0 を定義しています。