EN JA
VIS(3)
VIS(3) FreeBSD Library Functions Manual VIS(3)

名称

vis, nvis, strvis, strnvis, strvisx, strnvisx, strenvisx, svis, snvis, strsvis, strsnvis, strsvisx, strsnvisx, strsenvisx文字を視覚的にエンコード (符号化) する

ライブラリ

Standard C Library (libc, -lc)

書式

#include < vis.h>

char *
vis( char *dst, int c, int flag, int nextc);

char *
nvis( char *dst, size_t dlen, int c, int flag, int nextc);

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

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

int
strvisx( char *dst, const char *src, size_t len, int flag);

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

int
strenvisx( char *dst, size_t dlen, const char *src, size_t len, int flag, int *cerr_ptr);

char *
svis( char *dst, int c, int flag, int nextc, const char *extra);

char *
snvis( char *dst, size_t dlen, int c, int flag, int nextc, const char *extra);

int
strsvis( char *dst, const char *src, int flag, const char *extra);

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

int
strsvisx( char *dst, const char *src, size_t len, int flag, const char *extra);

int
strsnvisx( char *dst, size_t dlen, const char *src, size_t len, int flag, const char *extra);

int
strsenvisx( char *dst, size_t dlen, const char *src, size_t len, int flag, const char *extra, int *cerr_ptr);

解説

vis() 関数は、文字 c を表わす文字列を dst にコピーします。 c がエンコード(符号化) を必要としないなら、変更せずにコピーされます。文字列は、ヌル文字で終了し、文字列の終りへのポインタが返されます。あらゆるエンコードの最大の長さは、4 バイトです (後続する ヌル文字 は、含みません)。したがって、バッファに 1 組の文字をエンコードするとき、バッファのサイズは、後続する ヌル文字 の 1 を加えて、エンコードされたバイトの数の 4 倍であるべきです。 flag パラメータは、エンコードのためと視覚表現の変更のために考慮される文字のデフォルトの範囲の変更のために使用されます。追加の文字 nextc は、(下に説明された) VIS_CSTYLE エンコード形式を選択するときのみ使用されます。

strvis(), strnvis(), strvisx() と strnvisx() 関数は、文字列 src の視覚表現を dst コピーします。 strvis() と strnvis() 関数は、 src から最初の ヌル文字 までの文字をエンコードします。 strvisx() と strnvisx() 関数は、 src から正確に len 文字をエンコードします (これは、 ヌル文字 を含んでいるかもしれないデータのブロックをエンコードするために役に立ちます)。両方の形式の ヌル文字 は、 dst を終了します。 dst のサイズは、 src からエンコードされたバイト数の 4 倍でなければなりません ( ヌル文字 のために 1 加える)。両方の形式は、(後続する ヌル文字 を含まずに) dst の文字数を返します。また、関数の“ n”バージョンは、 dst バッファの長さを示す追加の引数 dlen をとります。 dlen が変換された文字列に適合するのには十分に大きくないなら、 strnvis() と strnvisx() 関数は、-1 を返し、 errnoENOSPC を設定します。 strenvisx() 関数は、マルチバイト変換エラーフラグを (内と外に) 渡すために使用される、追加の引数 cerr_ptr を取ります。これは、ロケールが入力データの文字のロケール以外の何かに設定されることが可能であるとき、単一文字を処理するとき、役に立ちます。

関数 svis(), snvis(), strsvis(), strsnvis(), strsvisx(), strsnvisx() と strsenvisx() は、 vis(), nvis(), strvis(), strnvis(), strvisx(), strnvisx() と strenvisx() に対応しますが、 ヌル文字 で終了する文字のリストを指す追加の引数 extra があります。これらの文字は、 dst にエンコードされるか、またはバックスラッシュでエスケープされてコピーされます。これらの関数は、例えば、シェルの特定の文字の特別の意味を削除するために役に立ちます。

エンコードは、全体にグラフィック文字から成るユニークで反転可能な表現です。それは、 unvis(3), strunvis(3) または strnunvis(3) 関数を使用して、元のオリジナルの形式にデコードすることができます。

制御することができる次の 2 つのパラメータがあります: ( vis(), nvis(), strvis(), strnvis(), strvisx() と strnvisx() にのみ適用される) エンコードされる文字の範囲と使用される表現のタイプ。デフォルトで、空白、タブと改行を除くすべての非グラフィック文字がエンコードされます ( isgraph(3) 参照)。次のフラグは、これを変更します:

VIS_GLOB
glob(3) によって認識されるマジック文字 (‘ *’, ‘ ?’, ‘ [’と‘ #’) もエンコードします。
VIS_SP
空白もエンコードします。
VIS_TAB
タブもエンコードします。
VIS_NL
改行もエンコードします。
VIS_WHITE
VIS_SP | VIS_TAB | VIS_NL と同義語です。
VIS_SAFE
“unsafe” (安全でない) 文字のみエンコードします。 unsafe (安全でない) は、一般的な端末に予期しない作用を行う制御文字を意味します。現在、この形式は、—すべてのグラフィック文字に加えて—エンコードされない空白、タブ、改行、バックスペース、ベルとリターンを許可します。

(上記のフラグは、 svis(), snvis(), strsvis(), strsnvis(), strsvisx() と strsnvisx() に効果がありません。これらの関数を使用するとき、 extra によって指される配列にエンコードされるすべてのグラフィック文字を置きます。一般的に、バックスラッシュ文字は、この配列に含まれているべきです、下記の VIS_NOSLASH フラグの使用に関する警告を参照してください)。

エンコードの 4 つの形式があります。すべての形式は、特別なシーケンスを導入するためにバックスラッシュ文字‘ \’を使用します。 2 つのバックスラッシュは、‘ %’を使用する VIS_HTTPSTYLE または‘ =’を使用する VIS_MIMESTYLE を除いて、実際のバックスラッシュを表わすために使用されます。これらは、視覚形式です:

(デフォルト)
(8 番目のビットが設定された文字) メタ文字を表わすために、‘ M’を使用し、制御文字 ( iscntrl(3) 参照) を表すためにキャレット‘ ^’を使用します。次の形式が使用されます:
\^C
制御文字‘ C’を表わします。文字‘ \000’から‘ \037’までの範囲と (‘ \^?’と表される) ‘ \177’。
\M-C
8番目のビットが設定された文字‘ C’を表わします。文字‘ \241’から‘ \376’の範囲。
\M^C
8番目のビットが設定された制御文字‘ C’を表わします。文字‘ \200’から‘ \237’の範囲と (‘ \M^?’と表される) ‘ \377’。
\040
ASCII の空白を表わします。
\240
メタ空白 (Meta-space) を表わします。
VIS_CSTYLE
標準の非印刷可能文字を表わすために C スタイルのバックスラッシュシーケンスを使用します。次のシーケンスが、示された文字を表わすために使用されます:

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

この形式を使用するとき、 nextc パラメータは、 ヌル 文字が‘ \000’の代わりに‘ \0’としてエンコードすることができるかどうか判断するために調べられます。 nextc が 8 進数字であるなら、後の表現が、曖昧さを避けるために使用されます。

VIS_OCTAL
3 桁の 8 進数のシーケンスを使用します。形式は、‘ \ddd’です、ここで d は、8 進数を表わします。
VIS_HTTPSTYLE
RFC 1738 に記述されているように URI エンコードを使用します。形式は、‘ %xx’です、ここで x は、小文字の 16 進数を表わします。
VIS_MIMESTYLE
単に行を改行せず、CRLF を扱わず、RFC 2045 に記述されているように MIME Quoted-Printable エンコードを使用します。形式は、‘ =XX’です、ここで X は、大文字の 16 進数を表わします。

デフォルトの形式 (すなわち、制御文字は、‘ ^C’によって表わされ、メタ文字は、‘ M-C’として表されます) の前の 2 つのバックスラッシュとバックスラッシュを抑制する、 1 つの追加のフラグ VIS_NOSLASH があります。このフラグを設定すると、エンコードは、曖昧で反転不可能です。

マルチバイト文字のサポート

これらの関数は、マルチバイト文字の入力をサポートしています。エンコーディング変換は、エンコーディング (符号化) なしでコピーすることができる文字のセットを定義する LC_CTYPE 環境変数の設定によって影響を受けます。

8 ビットのデータが入力に存在するとき、 LC_CTYPE は、正確なロケールまたは C ロケールに設定されなければなりません。データと変換のロケールが不一致であるなら、マルチバイト文字の認識は、失敗し、エンコーディング (符号化) は、代わりにバイトごとに実行されます。

上で注意されるように、 dst は、 src から処理されたバイトの数の 4 倍でなければなりません。しかし、各マルチバイト文字が MB_LEN_MAX バイトまで指定できるので、マルチバイト文字の観点では、 dst は、 src から処理された文字の数の MB_LEN_MAX 倍でなければならないことに注意してください。

環境変数

LC_CTYPE
入力データのロケールを指定します。入力データのロケールが未知であるなら、C に設定します。

エラー

関数 nvis() と snvis() は、 NULL を返し、関数 strnvis(), strnvisx(), strsnvis() と strsnvisx() は、 dlen 宛先バッファのサイズが変換を行なうの十分でないとき、-1 を返す一方、 errno に次を設定します:
[ ENOSPC]
宛先のバッファサイズが、変換を行なうために十分大きくありません。

関連項目

unvis(1), vis(1), glob(3), unvis(3) T. Berners-Lee, Uniform Resource Locators (URL), RFC 1738. Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, RFC 2045.

歴史

vis(), strvis() と strvisx() 関数は、 4.4BSD ではじめて登場しました。 svis(), strsvis() と strsvisx() 関数は、 NetBSD 1.5FreeBSD 9.2 で登場しました。 ( nvis(), strnvis(), strnvisx(), snvis(), strsnvis(), and strsnvisx()) 関数のバッファサイズ限定バージョンは、 NetBSD 6.0FreeBSD 9.2 で登場しました。マルチバイト文字のサポートは、 NetBSD 7.0FreeBSD 9.2 で追加されました。
February 19, 2013 FreeBSD