.\" Copyright (c) 1980, 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.
.\"
.\"     @(#)termcap.3	8.2 (Berkeley) 12/11/93
.\"
.\" $FreeBSD$
.Dd December 11, 1993
.Dt TERMCAP 3
.Os BSD 4
.Sh 名称
.Nm tgetent ,
.Nm tgetnum ,
.Nm tgetflag ,
.Nm tgetstr ,
.Nm tgoto ,
.Nm tputs ,
.Nm tparm ,
.Nm __set_ospeed
.Nd ターミナルとは独立した操作関数
.Sh 書式
.Fd #include <termcap.h>
.Vt char PC;
.Vt char *BC;
.Vt char *UP;
.Vt short ospeed;
.Ft int
.Fn tgetent "char *bp" "const char *name"
.Ft int
.Fn tgetnum "const char *id"
.Ft int
.Fn tgetflag "const char *id"
.Ft char *
.Fn tgetstr "const char *id" "char **area"
.Ft char *
.Fn tgoto "const char *cm" "int destcol" "int destline"
.Ft int
.Fn tputs "const char *cp" "int affcnt" "int (*outc)(int)"
.Ft char *
.Fn tparm "const char *cp" "..."
.Ft void
.Fn __set_ospeed "unsigned int speed"
.Sh 解説
これらの関数は、端末機能データベース、普通は
.Pa /usr/share/misc/termcap
から機能を抽出して使用し、その形式は
.Xr termcap 5
に説明してあります。
これらは低レベルのルーチンです。より高レベルのパッケージについては、
.Xr curses 3
を参照してください。
.Pp
.Fn tgetent
関数は、端末名の入力を
.Fa bp
のバッファに抽出します。引数
.Fa bp
はサイズ 1024 のキャラクタバッファでなければならず、またそれに続いて関数
.Fn tgetnum ,
.Fn tgetflag ,
.Fn tgetstr
などの呼び出しが行われても保持されます。
.Fn tgetent
関数は、データベースファイル
.Nm termcap
がどれも開けない場合は \-1 を返し、
与えた端末名が入力されていない場合は 0 を返し、すべてがうまく
処理された場合は 1 を返します。この関数は環境の中で
.Ev TERMCAP
変数を探します。それが見つかり、その値がスラッシュで始まっておらず、
また端末タイプ
.Fa name
が環境ストリング
.Ev TERM
と同じである場合は、
.Nm termcap
ファイルを読まずに
.Ev TERMCAP
ストリングを使用します。スラッシュで始まっている場合は、検索する
.Nm termcap
ファイルのパス名としてそのストリングを使います。
.Ev TERMCAP
がスラッシュで始まっておらす、かつ
.Fa name
が
.Ev TERM
と異なる場合は、環境変数
.Ev TERMPATH
が存在しなければ
.Fn tgetent
関数はファイル
.Pa $HOME/.termcap
および
.Pa /usr/share/misc/termcap
をこの順番で探します。
.Ev TERMPATH
が存在すれば、
それが検索するファイルの（空白またはコロンで区切られた）パス名リストを
指定します。複数のファイルを探す場合で要求されたエントリに
.Sy tc
フィールドがある場合は、
それが指名するエントリを同じファイルまたはそれに続くファイルの中に
探さねばなりません。これによって、
.Fn tgetent
関数を呼び出すプログラムへの
入力のスピードを上げることができるとともに、新しい端末記述のデバッグや
.Pa /usr/share/misc/termcap
ファイルを書けない場合に自分の端末の端末説明を
作ることが簡単になります。
.Pp
.Fn tgetnum
関数は、機能
.Fa id
の数値を取り入れて、それが端末に対して
与えられていない場合は \-1 を返します。
.Fn tgetflag
関数は、指定された機能が端末のエントリに存在する場合には 1 を返し、
存在しない場合には 0 を返します。
.Fn tgetstr
関数は、機能
.Fa id
のストリング値を返し、それを
.Fa area
のバッファに入れ、
.Fa area
ポインタを進めます。この関数は、カーソルのアドレス
およびパッディング情報を除いて、
.Xr termcap 5
に記述されたこのフィールドの
略称をデコードします。
.Fn tgetstr
関数は、その機能が見つからない場合は
.Dv NULL
を返します。
.Pp
.Fn tgoto
関数は、
.Fa destline
行の
.Fa cm
から go to カラムまででデコードされたカーソルアドレスストリングを返します。
この関数は、返すストリングに
.Sy \en ,
.Sy ^D
または
.Sy ^@
を入れることを避けるために必要な場合には外部変数
.Va UP
( 
.Sy up
機能から ) および
.Va BC
(
.Sy bs
ではなく
.Sy bc
が与えられている場合 ) を使います。(
.Fn tgoto
関数を呼び出すプログラムは、
.Fn tgoto
関数がタブを出力する可能性があるので、必ず
.Dv XTABS
ビットをオフにしておかなければなりません。
いずれにせよ、termcap を使っているプログラムは、
端末によっては control-I を他の機能、
例えば破壊不能スペースに使っているので、一般に
.Dv XTABS
をオフにする
必要があることに注意してください ) 。 理解できない
.Sy %
シーケンスが与えられている場合は、
.Fn tgoto
関数は
.Pq Dv OOPS
を返します。
.Pp
.Fn tputs
関数は、
.Fa cp
ストリングの先頭のパッディング情報をデコードします。
.Fa affcnt
は、この操作によって影響を受ける行数を与え、これに該当しない
場合は行数は 1 となり、
.Fa outc
は各キャラクタとともに順に呼び出されるルーチンです。外部変数
.Va PC
には、パッドキャラクタが null
.Pq Sy ^@
では不適当な場合には、( 
.Sy pc
機能から ) 使用すべきパッドキャラクタが
入っていなければなりません。
外部変数
.Va ospeed
には、
.Xr stty 3
によりエンコードされた端末の出力速度が
入っていなければなりません。
.Fn __set_ospeed
関数は、cps で表した速度
.Fa speed
をもっとも近い
.Xr stty 3
コード化された速度に変換し、その結果を
.Va ospeed
に保存します。
.Pp
.Fn tparm
関数は、ストリング
.Fa cp
を与えられたパラメータによってインスタンスに変換します。
.Fa cp
にそのパラメータが適用された結果を指すポインタ
が返されます。理解できない
.Sy %
シーケンスが与えられた場合は、
.Fn tparm
関数は
.Pq Dv OOPS
を返します。
.Sh ファイル
.Bl -tag -width /usr/share/misc/termcap -compact
.It /usr/lib/libtermcap.a
.Fl l Ar ltermcap
ライブラリ ( 
.Fl l Ar ltermlib 
とも呼ばれます )
.It /usr/share/misc/termcap
標準端末機能データベース
.It $HOME/.termcap
ユーザの端末機能データベース
.El
.Sh 参照
.Xr ex 1 ,
.Xr curses 3 ,
.Xr termcap 5
.Sh 歴史
.Fn tgetent
関数は、
.Bx 4.0
に現れました。