curs_terminfo(3x) curs_terminfo(3x)
del_curterm, mvcur, putp, restartterm, set_curterm,
setterm, setupterm, tigetflag, tigetnum, tigetstr, tiparm,
tparm, tputs, vid_attr, vid_puts, vidattr, vidputs
- terminfo データベースへの curses インターフェイス
#include <curses.h>
#include <term.h>
int setupterm(char *term, int fildes, int *errret);
int setterm(char *term);
TERMINAL *set_curterm(TERMINAL *nterm);
int del_curterm(TERMINAL *oterm);
int restartterm(char *term, int fildes, int *errret);
char *tparm(char *str, ...);
int tputs(const char *str, int affcnt, int (*putc)(int));
int putp(const char *str);
int vidputs(chtype attrs, int (*putc)(int));
int vidattr(chtype attrs);
int vid_puts(attr_t attrs, short pair, void *opts, int (*putc)(int));
int vid_attr(attr_t attrs, short pair, void *opts);
int mvcur(int oldrow, int oldcol, int newrow, int newcol);
int tigetflag(char *capname);
int tigetnum(char *capname);
char *tigetstr(char *capname);
char *tiparm(const char *str, ...);
例えばファンクションキーをプログラミングするような、
特定の端末機能項目 (ケーパビリティ) を取り扱うため、
terminfo データベースを直接扱う必要のあるプログラムは、
これらの低レベル・ルーチンを呼び出す必要があります。
他のすべての機能については、 curses ルーチンのほうが
適切であり、そちらの利用を推奨します。
最初に setupterm を呼び出す必要があります。
setupterm は initscr と newterm から自動的に呼び出される
ことに注意してください。
これは端末依存の変数 [terminfo(5) に一覧がある] の組を
定義します。
それぞれの初期化ルーチンは、直接に (ヘッダ定義を通して)、
または特別な関数により、アプリケーションに端末機能項目を
与えます。
これらの文字列、数値、フラグの定義を取得するために、
ヘッダファイル curses.h と term.h を (この順に) 取り込む
(include) 必要があります。
terminfo 変数 lines と columns は setupterm が次のように
初期化します。
o use_env(FALSE) が呼び出された場合、
terminfo で指定された lines と columns を使います。
o その他の場合、環境変数 LINES と COLUMUS が存在するならば、
それらの値を使います。
これらの環境変数が存在せず、プログラムをウインドウ内で
実行しているならば、現在のウインドウのサイズを使います。
上記以外の場合、これらの環境変数が存在しないならば、
terminfo データベースで指定されている lines と columns の
値を使います。
パラメータ化された文字列は、 tparm を通して渡し、
インスタンス化しなくてはなりません。
すべての terminfo 文字列 [tparm の出力を含む] は、
tputs か putp を使って出力 (print) しなくてはなりません。
終了 (exit) する前に reset_shell_mode を呼び出して
tty モードを復元しなくてはなりません。[curs_kernel(3x) 参照]
カーソル位置設定機能 (カーソル・アドレッシング) を用いる
プログラムは
o 開始時に enter_ca_mode を出力しなくてはなりません
o 終了前に exit_ca_mode を出力しなくてはなりません
シェルの子プロセスを実行するプログラムは
o シェルを呼び出す前に reset_shell_mode を呼び出し、
exit_ca_mode を出力しなくてはなりません
o シェルから戻った後に enter_ca_mode を出力し、
reset_prog_mode を呼び出さなくてはなりません
setupterm ルーチンは terminfo 構造(体)を初期化するときに、
terminfo データベースを読みますが、curses の使う
出力仮想化構造(体)を準備しません。
端末のタイプは文字列 term です。もし term がヌルならば、
環境変数 TERM が使われます。
すべての出力は、出力用に初期化されている
ファイル識別子 fildes へ送られます。
errret がヌルでない場合、setupterm は OK または ERR を返し、
状態値を errret が指す整数型領域に格納します。
戻り値 OK と errret 内の状態値 1 の組み合わせが正常です。
ERR を返した場合は errret を調べてください。
1 端末はハードコピー端末であり、curses アプリケーションは
使うことができません。
setupterm は hc (hardcopy) 機能項目を調べ、収録項目
(エントリ) がハードコピータイプかどうかを判定します。
0 端末が見つからないか、ジェネリックタイプ端末であって
情報が少なすぎるため、curses アプリケーションを
実行することができません。
setupterm は gn (generic) 機能項目を調べ、収録項目が
ジェネリックタイプかどうかを判定します。
-1 terminfo データベースが見つかりません。
errret がヌルの場合、setupterm はエラーを検出したとき
エラーメッセージを出力 (print) して終了します。
したがって、もっとも単純な呼び出しは
setupterm((char *)0, 1, (int *)0);,
で、すべてデフォルト値を使い、出力を stdout へ送ります。
setterm ルーチンは setupterm に置き換えられました。
setupterm(term, 1, (int *)0)
呼び出しは、setterm(term) と同じ動作をします。
setterm ルーチンは BSD との互換性のために用意されており、
新規のプログラムには推奨されません。
setupterm ルーチンは端末の情報を広域 (グローバル) 変数
cur_term の指す TERMINAL 構造体に格納します。
エラーを検出するか、端末が不適当 (ハードコピーまたは
ジェネリック) と判定した場合はこの情報を破棄し、
アプリケーションで使えないようにします。
setupterm を同じ端末タイプに対して繰り返して呼び出すと、
端末情報を再利用します。
与えられた端末の機能項目を 1 組しかメモリ上に保管しません。
setupterm を異なるタイプの端末に対して呼び出すと、それぞれの
端末機能項目情報の組を新たに割り当てます。
set_curterm ルーチンは cur_term を nterm にセットし、すべての
terminfo のブール値・数値・文字列変数が nterm からの値を
使うようにします。
このルーチンは cur_term の古い値を返します。
del_curterm ルーチンは oterm の指す領域を開放し、後で
使えるようにします。
oterm が cur_term と同じ場合、新たに setupterm を
呼び出すまで terminfo のブール値・数値・文字列変数への参照は
すべて無効なメモリ領域への参照となります。
restartterm ルーチンは、メモリを前の状態に戻した後で
呼び出される点を除いて setupterm と initscr と同じです
(例えば、コア・イメージ・ダンプとしてセーブしたゲームを
再ロードする時)。
restartterm はウインドウと入出力オプションが、メモリが
セーブされた時点と同じだと仮定しますが、端末タイプと
ボーレートは異なっているかもしれません。
したがって restartterm は種々の tty 状態ビットを保存し、
setupterm を呼び出し、それらのビットを復元します。
tparm ルーチンは、文字列 str を引数 pi とともに
インスタンス化します。(訳注: pi を使ってパラメータを評価します)
str に引数が適用された結果へのポインタを返します。
訳注: tparm() は可変引数ですが (移植性を参照)、他の実装では
char *tparm(char *str, long p1, long p2, long p3, long p4,
long p5, long p6, long p7, long p8, long p9);
のようになっています。
pi とあるのは p1, p2, ... を指しています。
tiparm は固定の引数リストでなく <stdarg.h>
(訳注: 可変引数リスト) を使う、tparm の新しい形式です。
数値引数は long ではなく整数 (int) です。
tputs ルーチンは、パディング情報を文字列 str に適用して
出力します。
str は terminfo の文字列変数、または tparm, tgetstr, tgoto
の戻り値でなければなりません。
affcnt は影響される行の数で、適用できない場合は 1 に
なります。
putc は一度に 1 つずつ文字を渡される putchar のような
ルーチンです。
putp ルーチンは tputs(str, 1, putchar) を呼び出します。
putp の出力は、setupterm で指定した fildes ではなく、
常に stdout へ行くことに注意してください。
vidputs ルーチンは文字列を curses(3x) にリストされたすべての
組み合わせの表示属性 (モード) attrs で端末に表示します。
文字は putchar のようなルーチン putc に渡されます。
vidattr ルーチンは vidputs に似ていますが、putchar を通して
出力する点だけが異なっています。
vid_attr と vid_puts ルーチンはそれぞれ vidattr と vidputs
ルーチンに対応しています。
この 2 つは表示属性と色を表す引数、すなわち属性を表す
attr_t 型と色のペアの番号を表す short 型を使います。
vid_attr と vid_puts ルーチンは WA_ で始まる属性定数を
使うように設計されています。
引数 opts は将来のために予約されています。
現在は、ヌルポインタを与えなければなりません。
mvcur ルーチンは低レベルのカーソル移動を行います。
これは即座に作用します (次の更新 (refresh) 時ではなく)。
tigetflag, tigetnum, tigetstr ルーチンは、xenl のように、
渡された terminfo の capname に対応する機能項目の値を返します。
各機能項目に対する capname は terminfo(5) の機能項目の節の
表の capname コードと題された列に与えられています。
これらのルーチンはエラーを示す特別な値を返します。
tigetflag ルーチンは次の値を返します。
-1 capname がブール値機能項目でないとき
0 端末記述から取り消されたか、欠落しているとき
tigetnum ルーチンは次の値を返します。
-2 capname が数値機能項目でないとき
-1 端末記述から取り消されたか、欠落しているとき
tigetstr ルーチンは次の値を返します。
(char *)-1
capname が文字列機能項目でないとき
0 端末記述から取り消されたか、欠落しているとき
これらのヌルで終わる配列は、定義済みの terminfo 変数の
それぞれについて、短い terminfo 名 ("codes")、termcap 名、
長い terminfo 名 ("fnames") を含んでいます。
char *boolnames[], *boolcodes[], *boolfnames[]
char *numnames[], *numcodes[], *numfnames[]
char *strnames[], *strcodes[], *strfnames[]
上のルーチン説明で特記していないかぎり、整数を返す
ルーチンは失敗のとき ERR を、正常終了のとき OK (SVr4 は
「ERR 以外の整数値」としか指定していません) を返します。
ポインタを返すルーチンは、エラーのとき常に NULL を返します。
X/Open はエラーの条件を何も定義していません。この実装では
del_curterm
その端末引数がヌルのときにエラーを返します。
putp は tputsを呼び出し、同じエラーコードを返します。
restartterm
これに伴う setupterm 呼び出しがエラーを返したときに
エラーを返します。
setupterm
十分なメモリを確保できなかったとき、または
初期ウインドウ (stdscr, curscr, newscr) を
作成できなかったときにエラーを返します。
他のエラー条件はすでに記しました。
tputs
文字列引数がヌルのときエラーを返します。
入出力 (I/O) エラーは検出しません。X/Open は、
tputs は出力関数 putc の戻り値を無視すると
明記しています。
X/Open はvidattr と vidputs はマクロであるかもしれないと
注意しています。
setterm 関数は X/Open に記述されておらず、
ポータブルではないと考えなくてはなりません。
他のすべての関数は X/Open に記述されている通りです。
setupterm は配列 ttytype に端末名をコピーします。
これは X/Open Curses の一部ではありませんが、一部の
アプリケーションからそうみなされています。
端末ドライバ、例えば MinGW port を使うように構成されている
場合には
o setupterm は変数 TERM がないか空のとき、
特別な値 "unknown" に変換します。
o setupterm は $TERM が "#win32con" またはその省略形で
あるかどうかを調べることにより、Windows コンソール・
ドライバを明示的に使うことを許しています。
古いバージョンの ncurses は、initscr または newterm から
setupterm に渡されたファイル記述子はバッファ付き入出力を
使用し、対応するストリームへ書き出すと仮定していました。
(SystemV curses のように) 終了時に端末がブロック入出力モード
のままになるという制限に加え、この仮定は問題の種でした。
それは ncurses が SIGTSTP を受け取ったときにクリーンアップ
するための信頼できる方法を許していなかったためです。
現在のバージョンは ncurses が直接管理する出力バッファを
使っています。
このマニュアル・ページで説明されている一部の低レベル関数は
標準出力へ書き込みます。
それらはシグナルに対して安全ではありません。
ncurses の高レベルルーチンは、より信頼できるバッファ機構を
使う、これらの関数の代替バージョンを使っています。
System V Release 4 では、set_curterm は int 型の戻り値を持ち、
OK または ERR を返します。
ncurses では X/Open Curses の解釈を実装することを
選択しました。
System V Release 4 では、tputs の第 3 引数の型は
int (*putc)(char) です。
X/Open Curses の少なくとも 1 つの実装 (Solaris) は、
tputs から OK/ERR 以外の値を返します。
それは文字列の長さを返し、エラーをチェックしません。
X/Open Curses は tparm を可変引数リストではなく、引数の数を
固定してプロトタイプ宣言しています。
この実装では可変引数リストを使っていますが、固定の
引数リストを使うように構成することもできます。
ポータブル・アプリケーションは書式文字列 (訳注: str) の後に
9 個の引数を与えてください。埋めるにはゼロが最適です。
Thomas E. Dickey の意見に応えて、X/Open Curses Issue 7 は
2009年の中頃に tiparm 関数を提案しました。
X/Open は mvcur を呼び出した後、curses の状態は実際の
端末の状態と一致しないことがあり、アプリケーションで
通常の curses 呼び出しを再開する前にウインドウのタッチ
(変更のマーク) と更新 (refresh) をしなければならないと
注意しています。
ncurses も System V Release 4 curses も、initscr または
newterm が割り当てた SCREEN データを使って mvcur を
実装しています。
mvcur は terminfo の関数として記述されてはいますが、
実際には詳しく仕様化されていない curses の関数です。
X/Open は mvcur に古い位置を与えなければならないと
明記しています。
この実装では古い座標として -1 を使うことを許しています。
この場合、古い位置は不明となります。
他の実装は機能項目名の配列を宣言していないことがあります。
いくつかの実装は、これらを宣言せずに提供しています。
X/Open はこれらを明記していません。
拡張された端末機能項目名、例えば tic -x によって
定義されたものは、ここで説明した配列の中に格納されません。
curses(3x), curs_initscr(3x), curs_kernel(3x),
curs_termcap(3x), curs_variables(3x), term_variables(3x),
putc(3), terminfo(5)
curs_terminfo(3x)