.\" 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.
.\"
.\"     From: @(#)vis.3	8.1 (Berkeley) 6/9/93
.\"	%Id: vis.3,v 1.7 1997/04/13 13:15:18 bde Exp %
.\"
.\" $FreeBSD$
.Dd July 25, 1996
.Dt VIS 3
.Os
.Sh 名称
.Nm vis
.Nd キャラクタを視覚的にコード化
.Sh 書式
.Fd #include <vis.h>
.Ft char *
.Fn vis "char *dst" "int c" "int flag" "int nextc"
.Ft int 
.Fn strvis "char *dst" "const char *src" "int flag"
.Ft int 
.Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
.Sh 解説
.Fn vis
関数は、キャラクタ
.Fa c
を表す文字列を
.Fa dst
にコピーします。
.Fa c
がコード化を必要としない場合は、何も変更せずにコピーします。
文字列は null で終端され、文字列の最後へのポインタが返されます。
コード化の長さの最大値は 4 キャラクタです ( 最後の
.Dv NUL
は含まない ) 。従って、キャラクタのセットを
バッファにコード化するときは、バッファのサイズはコード化される
キャラクタ数の 4 倍と、最後に付ける
.Dv NUL
の分の 1 が必要です。コード化する
キャラクタのデフォルト範囲を変更するため、また視覚的な表現を
変更するためにはフラグパラメータを使います。追加のキャラクタ、
.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 ) 。どちらの形式でも、キャラクタ数を
.Fa dst
に返します ( 最後の
.Dv NUL
は含まずに ) 。
.Pp
コード化は、すべてグラフィックキャラクタで構成されたユニークで
逆変換可能な表現です。すなわち、
.Xr unvis 3
または
.Xr strunvis 3
関数を使えば元の形に戻すことができます。
.Pp
制御できるパラメータは 2 つあります:コード化するキャラクタの範囲、
および使用する表現のタイプです。デフォルトでは、スペース、タブ、改行を
除くすべての非グラフィックキャラクタがコード化されます。( 
.Xr isgraph 3
参照 ) これは、以下のフラグによって変更されます:
.Bl -tag -width VIS_WHITEX
.It Dv VIS_SP
スペースもコード化します。
.It Dv VIS_TAB
タブもコード化します。
.It Dv VIS_NL
改行もコード化します。
.It VIS_WHITE
.Dv VIS_SP
\&|
.Dv VIS_TAB
\&| 
.Dv VIS_NL
と同義。
.It Dv VIS_SAFE
"unsafe" キャラクタのみをコード化します。"unsafe"キャラクタとは、
普通の端末に予期しない機能を引き起こすような制御キャラクタ
のことです。現在のところ、この形式ではすべてのグラフィックキャラクタに
加えて、スペース、タブ、改行、バックスペース、ベル、リターンを
コード化しないでおきます。
.El
.Pp
コード化には 3 つの形式があります。すべての形式は、
バックスラッシュキャラクタ
.Ql \e
を使って特殊シーケンスを導入します。本当のバックスラッシュを表すには、
 2 つのバックスラッシュを使います。次のような視覚的形式があります:
.Bl -tag -width VIS_CSTYLE
.It (default)
.Ql M
を使ってメタキャラクタ ( 8 番目のビットがセットされた
キャラクタ ) を表し、カラット
.Ql ^
を使って制御キャラクタを表します ( 
.Xr iscntrl 3
参照 ) 。
次のような形式を使います：
.Bl -tag -width xxxxx
.It Dv \e^C
制御キャラクタ
.Ql C
を表します。
.Ql \e000
から
.Ql \e037
まで、および
.Ql \e177
のキャラクタを
含みます ( 
.QL \e^?
のように ) 。
.It Dv \eM-C
8 番目のビットがセットされたキャラクタ
.Ql C
を表します。
.Ql \e241
から
.Ql \e377
までのキャラクタを含みます。
.It Dv \eM^C
8 番目のビットがセットされた制御キャラクタ
.Ql C
を表します。
.Ql \e200
から
.Ql \e237
まで、および
.QL \e377
のキャラクタを含みます (
.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
この形式を使う場合は、nextc パラメータを見て
.Dv NUL
キャラクタを
.Ql \e000
ではなく
.Ql \e0
とコード化するかどうかを判断します。
.Fa nextc
が 8 進数字である場合は、あいまいさを避けるために
.Ql \e000
の表現を使います。
.It Dv VIS_OCTAL
3 桁の 8 進法シーケンスを使います。
.Em d
が 8 進数字を表す場合は、形式は
.Ql \eddd
となります。
.El
.Pp
もう一つのフラグ、
.Dv VIS_NOSLASH
は、バックスラッシュの重複およびデフォルト形式 ( すなわち、
制御キャラクタを
.Ql ^C
で、メタキャラクタを
.Ql M-C
で表す形式 ) の前のバックスラッシュを抑制します。このフラグがセット
してあると、コード化はあいまいとなり逆変換不能となります。
.Sh 参照
.Xr unvis 1 ,
.Xr strunvis 3 ,
.Xr unvis 3
.Sh 歴史
これらの関数は最初に
.Bx 4.4
に現れました。