manual/netkit/release/man3/vis.3

   1 .\"     $OpenBSD: vis.3,v 1.3 1996/08/19 08:27:34 tholo Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\" Japanese Version Copyright (c) 2000 Yuichi SATO
  35 .\"         all rights reserved.
  36 .\" Translated Thu Dec 14 18:22:51 JST 2000
  37 .\"         by Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
  38 .\"
  39 .\"WORD:        visual representation   表示可能文字
  40 .\"
  41 .Dd June 9, 1993
  42 .Dt VIS 3
  43 .Os "Linux NetKit (0.17)"
  44 .Sh 名前
  45 .Nm vis
  46 .Nd 文字を表示可能文字にエンコードする
  47 .Sh 書式
  48 .Fd #include <vis.h>
  49 .Ft char *
  50 .Fn vis "char *dst" "char c" "int flag" "char nextc"
  51 .Ft int
  52 .Fn strvis "char *dst" "char *src" "int flag"
  53 .Ft int
  54 .Fn strvisx "char *dst" "char *src" "int len" "int flag"
  55 .Sh 説明
  56 .Fn vis
  57 関数は、文字
  58 .Fa c
  59 を表現する文字列を
  60 .Fa dst
  61 にコピーする。
  62 .Fa c
  63 をエンコードする必要がない場合、変更せずにコピーされる。
  64 文字列は NUL 文字で終端され、文字列の最後の文字へのポインタが返される。
  65 エンコードされた文字の最大長は 4 文字である (最後の
  66 .Dv NUL 文字
  67 は含まない)。
  68 よって、複数の文字をバッファにエンコードする場合、
  69 バッファの大きさは「エンコードされる文字の数の 4 倍 + 最後の
  70 .Dv NUL 文字
  71 のための 1 文字」でなければならない。
  72 引き数 flag は、エンコードまたは表示可能文字に変更される文字の
  73 デフォルトの範囲を変更する。
  74 その他の文字
  75 .Fa nextc
  76 は、エンコードフォーマット
  77 .Dv VIS_CSTYLE
  78 (以下で説明する) を選択する場合にのみ使われる。
  79 .Pp
  80 .Fn strvis
  81 と
  82 .Fn strvisx
  83 関数は、
  84 文字列
  85 .Fa src
  86 を表示可能文字にしたものを
  87 .Fa dst
  88 にコピーする。
  89 .Fn strvis
  90 関数は、
  91 .Fa src
  92 を
  93 .Dv NUL 文字
  94 が現れるまでエンコードする。
  95 .Fn strvisx
  96 関数は、
  97 .Fa src
  98 をちょうど
  99 .Fa len
 100 文字分だけエンコードする (これは
 101 .Dv NUL
 102 を含むデータブロックをエンコードするのに役立つ)。
 103 どちらの形式でも、
 104 .Fa dst
 105 は
 106 .Dv NUL
 107 終端される。
 108 .Fa dst
 109 の大きさは、エンコードされる文字
 110 .Fa src
 111 の数の 4 倍 (+
 112 .Dv NUL
 113 のための 1 文字分) でなければならない。
 114 どちらの形式でも dst の文字数が返される (最後の
 115 .Dv NUL
 116 は含まない)。
 117 .Pp
 118 エンコードは唯一のもので、全て表示文字から構成された可逆表現になっている。
 119 つまり、エンコードされた文字は、
 120 .Xr unvis 3
 121 や
 122 .Xr strunvis 3
 123 関数を用いて元の形式にデコードすることができる。
 124 .Pp
 125 制御可能な 2 つのパラメータがある:
 126 エンコードされる文字の範囲と使われる表現のタイプである。
 127 デフォルトでは、スペース・タブ・改行以外の非表示文字がエンコードされる
 128 .Ns ( Xr isgraph 3
 129 を参照)。
 130 以下のフラグは、この動作を変更する:
 131 .Bl -tag -width VIS_WHITEX
 132 .It Dv VIS_SP
 133 スペースもエンコードする。
 134 .It Dv VIS_TAB
 135 タブもエンコードする。
 136 .It Dv VIS_NL
 137 改行もエンコードする。
 138 .It Dv VIS_WHITE
 139 .Dv VIS_SP
 140 \&|
 141 .Dv VIS_TAB
 142 \&|
 143 .Dv VIS_NL
 144 と同じ。
 145 .It Dv VIS_SAFE
 146 「安全でない」文字だけをエンコードする。
 147 安全でないとは、一般的な端末に予期せぬ機能を動作させてしまうことを意味する。
 148 現在のところ、スペース・タブ・改行・バックスペース・ベル・リターン
 149 - そして全ての表示可能文字 - はエンコードされない。
 150 .El
 151 .Pp
 152 3 つのエンコード形式がある。
 153 全ての形式で、バックスペース
 154 .Ql \e
 155 が特殊シーケンスの始まりとして使われる。
 156 2 つのバックスペースが実際のバックスペースを表現するために使われる。
 157 以下のような可視化フォーマットがある:
 158 .Bl -tag -width VIS_CSTYLE
 159 .It (デフォルト)
 160 メタ文字 (8 ビット目を使う文字) を表現するためには、
 161 .Ql M
 162 を使うこと。
 163 制御文字
 164 .Pf ( Xr iscntrl 3
 165 を参照) を表現するためには、キャレット
 166 .Ql ^
 167 を使うこと。
 168 以下のフォーマットが使われる:
 169 .Bl -tag -width xxxxx
 170 .It Dv \e^C
 171 制御文字
 172 .Ql C
 173 を表す。
 174 .Ql \e000
 175 から
 176 .Ql \e037
 177 の間の文字と
 178 .Ql \e177
 179 .Ns ( Ql \e^?
 180 と同じ) を表す。
 181 .It Dv \eM-C
 182 8 ビット目がセットされている文字
 183 .Ql C
 184 を表す。
 185 .Ql \e241
 186 から
 187 .Ql \e376
 188 の間の文字を表す。
 189 .It Dv \eM^C
 190 8 ビット目がセットされている制御文字
 191 .Ql C
 192 を表す。
 193 with the 8th bit set.
 194 Spans characters
 195 .Ql \e200
 196 から
 197 .Ql \e237
 198 の間の文字と
 199 .Ql \e377
 200 .Ns ( Ql \eM^?
 201 と同じ) を表す。
 202 .It Dv \e040
 203 .Tn ASCII
 204 スペースを表す。
 205 .It Dv \e240
 206 メタスペースを表す。
 207 .El
 208 .Pp
 209 .It Dv VIS_CSTYLE
 210 標準的な非表示文字を表現するために、
 211 C 言語形式のバックスラッシュシーケンスを使う。
 212 このような文字を表すために以下のシーケンスが使われる:
 213 .Bd -unfilled -offset indent
 214 .Li \ea Tn  - BEL No (007)
 215 .Li \eb Tn  - BS No (010)
 216 .Li \ef Tn  - NP No (014)
 217 .Li \en Tn  - NL No (012)
 218 .Li \er Tn  - CR No (015)
 219 .Li \et Tn  - HT No (011)
 220 .Li \ev Tn  - VT No (013)
 221 .Li \e0 Tn  - NUL No (000)
 222 .Ed
 223 .Pp
 224 このフォーマットを使った場合、
 225 .Dv NUL
 226 文字を
 227 .Ql \e000
 228 ではなく
 229 .Ql \e0
 230 としてエンコードするかを決定するために、引き数 nextc が参照される。
 231 .Fa nextc
 232 が 1 個の 8 進数の場合、曖昧さを避けるため後者の表現が使われる。
 233 .It Dv VIS_OCTAL
 234 3 個の 8 進数シーケンスを使う。
 235 .Ql \eddd
 236 という形式が使われる。
 237 ここで
 238 .Em d
 239 は 8 進数を表す。
 240 .El
 241 .Pp
 242 さらに、もう 1 つフラグ
 243 .Dv VIS_NOSLASH
 244 がある。
 245 このフラグは、2 つのバックスラッシュと
 246 デフォルトフォーマットで前におかれるバックスラッシュを使わないようにする。
 247 (つまり、制御文字は
 248 .Ql ^C
 249 で、メタ文字は
 250 .Ql M-C
 251 で表される)。
 252 このフラグが設定されると、エンコードは曖昧で可逆でなくなる。
 253 .Sh 関連項目
 254 .Xr vis 1 ,
 255 .Xr unvis 1 ,
 256 .Xr unvis 3
 257 .Sh 履歴
 258 これらの関数は 4.4BSD で初めて登場した。