VIS(3)

名称
vis - キャラクタを視覚的にコード化

ライブラリ
libc

書式
<vis.h> char * vis(char *dst, int c, int flag, int nextc) int strvis(char *dst, const char *src, int flag) int strvisx(char *dst, const char *src, size_t len, int flag)

解説
vis() 関数は、キャラクタ c を表す文字列を dst にコピーします。 c がコード化を必要としない場合は、何も変更せずにコピーします。 文字列は null で終端され、文字列の最後へのポインタが返されます。 コード化の長さの最大値は 4 キャラクタです (最後の NUL は含まない)。従って、キャラクタのセットを バッファにコード化するときは、バッファのサイズはコード化される キャラクタ数の 4 倍と、最後に付ける NUL の分の 1 が必要です。コード化する キャラクタのデフォルト範囲を変更するため、また視覚的な表現を 変更するためにはフラグパラメータを使います。追加のキャラクタ、 nextc は、コード化形式 VIS_CSTYLE を選択したときにのみ使います (以下に説明します)。

strvis() および strvisx() 関数は、文字列 src の視覚的表現を dst にコピーします。 strvis() 関数は、 src から最初の NUL までのキャラクタをコード化します。 strvisx() 関数は、 src から正確に len 個のキャラクタをコード化します (これは、複数の NUL を含む可能性のあるデータのブロックを コード化する場合に役に立ちます)。どちらの形式でも dst を NUL で終端します。 dst のサイズは、 src からコード化されるキャラクタ数の 4 倍でなければなりません (プラス NUL のための 1)。どちらの形式でも、キャラクタ数を dst に返します (最後の NUL は含まずに)。

コード化は、すべてグラフィックキャラクタで構成されたユニークで 逆変換可能な表現です。すなわち、 unvis(3) または strunvis(3) 関数を使えば元の形に戻すことができます。

制御できるパラメータは 2 つあります:コード化するキャラクタの範囲、 および使用する表現のタイプです。デフォルトでは、スペース、タブ、改行を 除くすべての非グラフィックキャラクタがコード化されます。( isgraph(3) 参照) これは、以下のフラグによって変更されます:

VIS_SP
    スペースもコード化します。

VIS_TAB
    タブもコード化します。

VIS_NL
    改行もコード化します。

VIS_WHITE
    VIS_SP | VIS_TAB | VIS_NL と同義。

VIS_SAFE
    "unsafe" キャラクタのみをコード化します。"unsafe"キャラクタとは、 普通の端末に予期しない機能を引き起こすような制御キャラクタ のことです。現在のところ、この形式ではすべてのグラフィックキャラクタに 加えて、スペース、タブ、改行、バックスペース、ベル、リターンを コード化しないでおきます。

コード化には 4 つの形式があります。すべての形式は、 バックスラッシュキャラクタ ‘\’ を使って特殊シーケンスを導入します。本当のバックスラッシュを表すには、 2 つのバックスラッシュを使います。次のような視覚的形式があります:

(default)
    ‘M’ を使ってメタキャラクタ (8 番目のビットがセットされた キャラクタ) を表し、カラット ‘^’ を使って制御キャラクタを表します ( iscntrl(3) 参照)。 次のような形式を使います：

    \^C 制御キャラクタ ‘C’ を表します。 ‘\000’ から ‘\037’ まで、および ‘\177’ のキャラクタを 含みます ( のように)。

    \M-C
        8 番目のビットがセットされたキャラクタ ‘C’ を表します。 ‘\241’ から ‘\377’ までのキャラクタを含みます。

    \M^C
        8 番目のビットがセットされた制御キャラクタ ‘C’ を表します。 ‘\200’ から ‘\237’ まで、および のキャラクタを含みます ( ‘\M^?’ のように)。

    \040
        ASCII のスペースを表します。

    \240
        メタスペースを表します。

VIS_CSTYLE
    C スタイルのバックスラッシュシーケンスを使って、標準非印刷 キャラクタを表します。次に示すシーケンスを使って、指定されているキャラクタ を表します：

        \a - BEL (007)
        \b - BS (010)
        \f - NP (014)
        \n - NL (012)
        \r - CR (015)
        \t - HT (011)
        \v - VT (013)
        \0 - NUL (000)

    この形式を使う場合は、nextc パラメータを見て NUL キャラクタを ‘\000’ ではなく ‘\0’ とコード化するかどうかを判断します。 nextc が 8 進数字である場合は、あいまいさを避けるために ‘\000’ の表現を使います。

VIS_HTTPSTYLE
    RFC 1808 に記述された URI エンコードを使用します。 形式は ‘%dd’ であり、 d は、16 進数の桁を表現します。

VIS_OCTAL
    3 桁の 8 進法シーケンスを使います。 d が 8 進数字を表す場合は、形式は ‘\ddd’ となります。

もう一つのフラグ、 VIS_NOSLASH は、バックスラッシュの重複およびデフォルト形式 (すなわち、 制御キャラクタを ‘^C’ で、メタキャラクタを ‘M-C’ で表す形式) の前のバックスラッシュを抑制します。このフラグがセット してあると、コード化はあいまいとなり逆変換不能となります。

関連項目
unvis(1), unvis(3) R. Fielding, Relative Uniform Resource Locators, RFC1808.

歴史
これらの関数は 4.4BSD ではじめて登場しました。