UNVIS(3) | FreeBSD Library Functions Manual | UNVIS(3) |
名称
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() 関数は、 4.4BSD ではじめて登場しました。 strnunvis() と strnunvisx() 関数は、 NetBSD 6.0 と FreeBSD 9.2 で登場しました。バグ
名前 VIS_HTTP1808 と VIS_HTTP1866 は、間違っています。パーセントエンコーディング (符号化) は、URL のためのオリジナルの RFC である、 RFC 1738 定義されました。 RFC 1866 は、番号文字の参照と実体の参照の概念を継承する、 SGML のアプリケーション、HTML 2.0 を定義しています。March 12, 2011 | FreeBSD |