.\"	$OpenBSD: vis.3,v 1.3 1996/08/19 08:27:34 tholo Exp $
.\"
.\" 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.
.\"
.\" Japanese Version Copyright (c) 2000 Yuichi SATO
.\"         all rights reserved.
.\" Translated Thu Dec 14 18:22:51 JST 2000
.\"         by Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
.\"
.\"WORD:	visual representation	表示可能文字
.\"
.Dd June 9, 1993
.Dt VIS 3
.Os "Linux NetKit (0.17)"
.Sh 名前
.Nm vis
.Nd 文字を表示可能文字にエンコードする
.Sh 書式
.Fd #include <vis.h>
.Ft char *
.Fn vis "char *dst" "char c" "int flag" "char nextc"
.Ft int 
.Fn strvis "char *dst" "char *src" "int flag"
.Ft int 
.Fn strvisx "char *dst" "char *src" "int len" "int flag"
.Sh 説明
.Fn vis
関数は、文字
.Fa c
を表現する文字列を
.Fa dst
にコピーする。
.Fa c
をエンコードする必要がない場合、変更せずにコピーされる。
文字列は NUL 文字で終端され、文字列の最後の文字へのポインタが返される。
エンコードされた文字の最大長は 4 文字である (最後の
.Dv NUL 文字
は含まない)。
よって、複数の文字をバッファにエンコードする場合、
バッファの大きさは「エンコードされる文字の数の 4 倍 + 最後の
.Dv NUL 文字
のための 1 文字」でなければならない。
引き数 flag は、エンコードまたは表示可能文字に変更される文字の
デフォルトの範囲を変更する。
その他の文字
.Fa nextc
は、エンコードフォーマット
.Dv VIS_CSTYLE
(以下で説明する) を選択する場合にのみ使われる。
.Pp
.Fn strvis
と
.Fn strvisx
関数は、
文字列
.Fa src
を表示可能文字にしたものを
.Fa dst
にコピーする。
.Fn strvis
関数は、
.Fa src
を
.Dv NUL 文字 
が現れるまでエンコードする。
.Fn strvisx
関数は、
.Fa src
をちょうど
.Fa len
文字分だけエンコードする (これは
.Dv NUL
を含むデータブロックをエンコードするのに役立つ)。
どちらの形式でも、
.Fa dst
は
.Dv NUL
終端される。
.Fa dst
の大きさは、エンコードされる文字
.Fa src
の数の 4 倍 (+
.Dv NUL
のための 1 文字分) でなければならない。
どちらの形式でも dst の文字数が返される (最後の
.Dv NUL
は含まない)。
.Pp
エンコードは唯一のもので、全て表示文字から構成された可逆表現になっている。
つまり、エンコードされた文字は、
.Xr unvis 3
や
.Xr strunvis 3
関数を用いて元の形式にデコードすることができる。
.Pp
制御可能な 2 つのパラメータがある:
エンコードされる文字の範囲と使われる表現のタイプである。
デフォルトでは、スペース・タブ・改行以外の非表示文字がエンコードされる
.Ns ( Xr isgraph 3
を参照)。
以下のフラグは、この動作を変更する:
.Bl -tag -width VIS_WHITEX
.It Dv VIS_SP
スペースもエンコードする。
.It Dv VIS_TAB		
タブもエンコードする。
.It Dv VIS_NL
改行もエンコードする。
.It Dv VIS_WHITE	
.Dv VIS_SP
\&|
.Dv VIS_TAB
\&|
.Dv VIS_NL
と同じ。
.It Dv VIS_SAFE	
「安全でない」文字だけをエンコードする。
安全でないとは、一般的な端末に予期せぬ機能を動作させてしまうことを意味する。
現在のところ、スペース・タブ・改行・バックスペース・ベル・リターン
- そして全ての表示可能文字 - はエンコードされない。
.El
.Pp
3 つのエンコード形式がある。
全ての形式で、バックスペース
.Ql \e
が特殊シーケンスの始まりとして使われる。
2 つのバックスペースが実際のバックスペースを表現するために使われる。
以下のような可視化フォーマットがある:
.Bl -tag -width VIS_CSTYLE
.It (デフォルト)
メタ文字 (8 ビット目を使う文字) を表現するためには、
.Ql M
を使うこと。
制御文字
.Pf ( Xr iscntrl 3
を参照) を表現するためには、キャレット
.Ql ^
を使うこと。
以下のフォーマットが使われる:
.Bl -tag -width xxxxx
.It Dv \e^C
制御文字
.Ql C
を表す。
.Ql \e000
から
.Ql \e037
の間の文字と
.Ql \e177
.Ns ( Ql \e^?
と同じ) を表す。
.It Dv \eM-C
8 ビット目がセットされている文字
.Ql C
を表す。
.Ql \e241
から
.Ql \e376
の間の文字を表す。
.It Dv \eM^C
8 ビット目がセットされている制御文字
.Ql C
を表す。
with the 8th bit set.
Spans characters
.Ql \e200
から
.Ql \e237
の間の文字と
.Ql \e377
.Ns ( Ql \eM^?
と同じ) を表す。
.It Dv \e040
.Tn ASCII
スペースを表す。
.It Dv \e240
メタスペースを表す。
.El
.Pp
.It Dv VIS_CSTYLE
標準的な非表示文字を表現するために、
C 言語形式のバックスラッシュシーケンスを使う。
このような文字を表すために以下のシーケンスが使われる:
.Bd -unfilled -offset indent
.Li \ea Tn  - BEL No (007)
.Li \eb Tn  - BS No (010)
.Li \ef Tn  - NP No (014)
.Li \en Tn  - NL No (012)
.Li \er Tn  - CR No (015)
.Li \et Tn  - HT No (011)
.Li \ev Tn  - VT No (013)
.Li \e0 Tn  - NUL No (000)
.Ed
.Pp
このフォーマットを使った場合、
.Dv NUL
文字を
.Ql \e000
ではなく
.Ql \e0
としてエンコードするかを決定するために、引き数 nextc が参照される。
.Fa nextc
が 1 個の 8 進数の場合、曖昧さを避けるため後者の表現が使われる。
.It Dv VIS_OCTAL
3 個の 8 進数シーケンスを使う。
.Ql \eddd
という形式が使われる。
ここで
.Em d
は 8 進数を表す。
.El
.Pp
さらに、もう 1 つフラグ
.Dv VIS_NOSLASH
がある。
このフラグは、2 つのバックスラッシュと
デフォルトフォーマットで前におかれるバックスラッシュを使わないようにする。
(つまり、制御文字は
.Ql ^C
で、メタ文字は
.Ql M-C
で表される)。
このフラグが設定されると、エンコードは曖昧で可逆でなくなる。
.Sh 関連項目
.Xr vis 1 ,
.Xr unvis 1 ,
.Xr unvis 3
.Sh 履歴
これらの関数は 4.4BSD で初めて登場した。