curs_util 3x

curs_util(3x)                                             curs_util(3x)




NAME 名前

       delay_output, filter, flushinp, getwin, key_name, keyname,
       nofilter, putwin, unctrl, use_env, use_tioctl, wunctrl -
       miscellaneous curses utility routines
       - 種々の curses ユーティリティ・ルーチン


SYNOPSIS 書式

       #include <curses.h>

       char *unctrl(chtype c);
       wchar_t *wunctrl(cchar_t *c);
       char *keyname(int c);
       char *key_name(wchar_t w);
       void filter(void);
       void nofilter(void);
       void use_env(bool f);
       void use_tioctl(bool f);
       int putwin(WINDOW *win, FILE *filep);
       WINDOW *getwin(FILE *filep);
       int delay_output(int ms);
       int flushinp(void);


DESCRIPTION 説明


unctrl/wunctrl

       The  unctrl  routine returns a character string which is a
       printable representation of the character c, ignoring  at-
       tributes.   Control characters are displayed in the ^X no-
       tation.  Printing characters are  displayed  as  is.   The
       corresponding  wunctrl  returns a printable representation
       of a wide character.
        unctrl ルーチンは文字 c の印字可能な表現を文字列として
       返します。属性は無視されます。
        制御文字は ^X の形式で表示されます。
        印字可能文字はそのまま表示されます。
        対応する wunctrl はワイド文字の印字可能な表現を返します。


keyname/key_name

       The keyname routine returns a character string correspond-
       ing to the key c:
        keyname ルーチンはキー c に対応する文字列を返します。

       o   Printable  characters  are  displayed  as  themselves,
           e.g., a one-character string containing the key.
       o   印字可能文字はそれ自身を表示します。
           たとえば、そのキーを含む 1 文字の文字列です。

       o   Control characters are displayed in the ^X notation.
       o   制御文字は ^X の形式で表示されます。

       o   DEL (character 127) is displayed as ^?.
       o   DEL (コード 127) は ^? と表示されます。

       o   Values above 128 are either meta  characters  (if  the
           screen  has  not been initialized, or if meta has been
           called with a TRUE parameter), shown in the M-X  nota-
           tion,  or  are displayed as themselves.  In the latter
           case, the values may not be  printable;  this  follows
           the X/Open specification.
       o   128 以上の値は、M-X の形式で表示される
           メタ文字 (画面が初期化されていないか、meta を
           引数 TRUE とともに呼び出したとき) か、またはそのまま
           表示されます。
           後者の場合、値は印字可能でないことがあります。これは 
           X/Open の仕様によるものです。
           (訳注: meta 関数は curs_inopts(3x) を参照)

       o   Values  above  256  may  be  the names of the names of
           function keys.
       o   256 以上の値はファンクションキーの名前の
           名前であることがあります。(訳注: 原文どおり)

       o   Otherwise (if there  is  no  corresponding  name)  the
           function returns null, to denote an error.  X/Open al-
           so lists an "UNKNOWN KEY" return value, which some im-
           plementations return rather than null.
            さもなければ (対応する名前がない場合) エラーを知らせるため
           関数はヌルを返します。
            X/Open はいくつかの実装がヌルの代わりに返す 
           "UNKNOWN KEY" という戻り値を載せています。

       The corresponding key_name returns a character string cor-
       responding to the wide-character value w.  The  two  func-
       tions  do  not  return the same set of strings; the latter
       returns null where the former would display a meta charac-
       ter.
        対応する key_name はワイド文字値 w に対応する文字列を
       返します。
        これら 2 つの関数は同じ文字列の組を返しません。前者が
       メタ文字を表示するところで、後者はヌルを返します。


filter/nofilter

       The filter routine, if used, must be called before initscr
       or newterm are called.  The effect is that,  during  those
       calls,  LINES  is  set  to 1; the capabilities clear, cup,
       cud, cud1, cuu1, cuu,  vpa  are  disabled;  and  the  home
       string is set to the value of cr.
        filter ルーチンを使うときは、initscr または newterm を
       呼び出す前に呼び出さなければなりません。
        filter の効果は、これらの呼び出しの間、LINES を 1 に設定し、 
       clear, cup, cud, cud1, cuu1, cuu, vpa の機能項目を無効にし、
       home 文字列を cr の値に設定します。

       The  nofilter  routine  cancels  the effect of a preceding
       filter call.  That  allows  the  caller  to  initialize  a
       screen  on  a different device, using a different value of
       $TERM.  The limitation arises because the  filter  routine
       modifies the in-memory copy of the terminal information.
        nofilter ルーチンは先行する filter 呼び出しの効果を
       取り消します。
        これにより、異なるデバイス上の画面を異なった $TERM の値で
       初期化することができるようになります。
        filter ルーチンはメモリ上にある端末情報のコピーを修正するため、
       制約が生じます。


use_env

       The  use_env  routine,  if  used,  should be called before
       initscr or newterm are called (because those  compute  the
       screen size).  It modifies the way ncurses treats environ-
       ment variables when determining the screen size.
        use_env ルーチンを使うときは、initscr または newterm を
       呼び出す前に呼び出さなければなりません。(それらは画面の
       サイズを計算するためです。)
        このルーチンは ncurses が画面のサイズを決定する時に
       環境変数を扱う方法を変更します。

       o   Normally ncurses looks first at the terminal  database
           for the screen size.
       o   通常 ncurses は最初に端末データベースで画面のサイズを
           調べます。

           If  use_env  was  called  with FALSE for parameter, it
           stops here unless If use_tioctl was also  called  with
           TRUE for parameter.
           use_env が引数 FALSE とともに呼び出された場合、
           use_tioctl が引数 TRUE とともに呼び出されないかぎり、
           ここで止めます。

       o   Then  it asks for the screen size via operating system
           calls.  If successful, it overrides  the  values  from
           the terminal database.
       o   次にオペレーティング・システム呼び出しにより画面のサイズを
           問い合わせます。成功した場合、端末データベースからの値は
           上書きされます。

       o   Finally  (unless use_env was called with FALSE parame-
           ter), ncurses examines the LINES or  COLUMNS  environ-
           ment variables, using a value in those to override the
           results from the operating system  or  terminal  data-
           base.
       o   最後に (use_env が引数 FALSE とともに呼び出されていない
           かぎり) ncurses は環境変数 LINES または COLUMNS を調べ、
           それらの値を使ってオペレーティング・システムからの
           または端末データベースからの結果を上書きします。

           Ncurses  also  updates  the screen size in response to
           SIGWINCH, unless overridden by the  LINES  or  COLUMNS
           environment variables,
           ncurses はまた、環境変数 LINES または COLUMNS で上書き
           されない限り SIGWINCH への応答として画面サイズを
           変更します。
            (訳注: resizeterm(3x), curs_initscr(3x) 参照)

use_tioctl

       The  use_tioctl  routine, if used, should be called before
       initscr or newterm are called (because those  compute  the
       screen  size).  After use_tioctl is called with TRUE as an
       argument, ncurses modifies the last step in  its  computa-
       tion of screen size as follows:
        use_tioctl ルーチンを使うときは、initscr または newterm を
       呼び出す前に呼び出さなければなりません。(それらは画面の
       サイズを計算するためです。)
        use_tioctl が引数 TRUE とともに呼び出された後、ncurses は
       画面サイズを計算する最後の段階を次のように変更します。

       o   checks  if the LINES and COLUMNS environment variables
           are set to a number greater than zero.
       o   環境変数 LINESCOLUMNS が 0 より大きい値に
           設定されていることを確かめます。

       o   for each, ncurses updates the  corresponding  environ-
           ment  variable with the value that it has obtained via
           operating system call or from the terminal database.
       o   それぞれについて、ncurses は対応する環境変数の値を
           オペレーティング・システム呼び出し経由で得た値または
           端末データベースからの値で更新します。

       o   ncurses re-fetches the value of the environment  vari-
           ables  so  that  it is still the environment variables
           which set the screen size.
       o   画面のサイズを設定したこれらの環境変数をそのまま保持する
           ために、ncurses はこれらの環境変数の値を再度読み出します。

       The use_env and use_tioctl routines combine as  summarized
       here:
        use_envuse_tioctl ルーチンの組み合わせは次のように
       まとめられます。

     use_env   use_tioctl   Summary
     use_env   use_tioctl   まとめ
     ----------------------------------------------------------------



     TRUE      FALSE        This  is  the default behavior.  ncurses
                            uses operating system calls unless over-
                            ridden by $LINES or $COLUMNS environment
                            variables.
     TRUE      FALSE        これはデフォルトの動作です。
                            ncurses は環境変数 $LINES または $COLUMNS 
                            で上書きされない限りオペレーティング・
                            システム呼び出しを使います。
     TRUE      TRUE         ncurses  updates  $LINES  and   $COLUMNS
                            based on operating system calls.
     TRUE      TRUE         ncurses はオペレーティング・システム
                            呼び出しに基づいて $LINES と $COLUMNS を
                            更新します。
     FALSE     TRUE         ncurses ignores $LINES and $COLUMNS, us-
                            es  operating  system  calls  to  obtain
                            size.
     FALSE     TRUE         ncurses は $LINES と $COLUMNS を無視し、
                            サイズを得るためにオペレーティング・
                            システム呼び出しを使います。
     FALSE     FALSE        ncurses  relies on the terminal database
                            to determine size.
     FALSE     FALSE        ncurses は端末データベースに依って
                            サイズを決定します。


putwin/getwin

       The putwin routine writes all data associated with  window
       (or  pad)  win  into the file to which filep points.  This
       information can be later retrieved using the getwin  func-
       tion.
        putwin ルーチンはウインドウ (またはパッド) win に関連する
       すべてのデータを filep が指すファイルへ書き出します。
        この情報は後で getwin 関数を使って復元することができます。

       The getwin routine reads window related data stored in the
       file by putwin.  The routine then creates and  initializes
       a new window using that data.  It returns a pointer to the
       new window.  There are a few caveats:
        getwin ルーチンは putwin でファイルに書き込まれた
       ウインドウに関連するデータを読み出します。
        次に、このルーチンはそのデータを使って新しいウインドウを
       作成して初期化します。
        このルーチンは新しいウインドウへのポインタを返します。
        いくつかの注意点を下に示します。

       o   the data written is a copy of  the  WINDOW  structure,
           and  its  associated character cells.  The format dif-
           fers between the wide-character  (ncursesw)  and  non-
           wide  (ncurses)  libraries.  You can transfer data be-
           tween the two, however.
       o   書き込まれたデータは WINDOW  構造体と、これに伴う文字の
           マスのコピーです。
           フォーマットはワイド文字用ライブラリ (ncursesw) と 
           1 バイト用ライブラリ (ncurses) で異なります。
           しかし、両者の間でデータを移すこともできます。

       o   the retrieved window is always created as a  top-level
           window (or pad), rather than a subwindow.
       o   復元されたウインドウは子ウインドウではなく、常に最上位
           レベルのウインドウ (またはパッド) として作成されます。

       o   the  window's  character  cells contain the color pair
           value, but not the actual color numbers.  If cells  in
           the  retrieved  window  use color pairs which have not
           been created in the application using init_pair,  they
           will not be colored when the window is refreshed.
       o   ウインドウ内の文字のマスは色のペアのを含みますが、実際の
           色の番号を含みません。
           アプリケーションで init_pair, を使って作成されていない
           色のペアを復元されたウインドウ中のマスが使っている場合、
           ウインドウを更新 (refresh) しても保存した時の色で
           表示されません。


delay_output

       The  delay_output  routine inserts an ms millisecond pause
       in output.  This routine should not  be  used  extensively
       because  padding  characters  are  used  rather than a CPU
       pause.  If no padding character is  specified,  this  uses
       napms to perform the delay.
        delay_output ルーチンは ms ミリ秒の休止を出力に挿入します。
        CPU を休止せず、パディング文字を使うので、このルーチンを
       広範に使ってはいけません。
        パディング文字が指定されていない場合は、遅延を実行するために 
       napms が使われます。


flushinp

       The  flushinp  routine  throws away any typeahead that has
       been typed by the user and has not yet been  read  by  the
       program.
        flushinp ルーチンはすでにタイプされてまだプログラムが
       読んでいない先読み入力をすべて破棄します。


RETURN VALUE 戻り値

       Except  for  flushinp, routines that return an integer re-
       turn ERR upon failure and OK (SVr4 specifies only "an  in-
       teger value other than ERR") upon successful completion.
        flushinp を除き、整数を返すルーチンは、失敗のとき ERR を、
       正常終了のとき OK (SVr4 は「ERR 以外の整数値」としか
       指定していません) を返します。

       Routines that return pointers return NULL on error.
        ポインタを返すルーチンはエラーのとき NULL を返します。

       X/Open  does not define any error conditions.  In this im-
       plementation
       X/Open はエラーの条件を何も定義していません。この実装では

          flushinp
               returns an error if the terminal was not  initial-
               ized.
               端末が初期化されていなかった場合にエラーを返します。

          meta returns  an error if the terminal was not initial-
               ized.
               端末が初期化されていなかった場合にエラーを返します。
               (訳注: meta 関数は curs_inopts(3x) を参照)

          putwin
               returns an error if the  associated  fwrite  calls
               return an error.
               これに伴う fwrite 呼び出しがエラーを返した場合に
               エラーを返します。


PORTABILITY 移植性


filter

       The SVr4 documentation describes the action of filter only
       in the vaguest terms.  The  description  here  is  adapted
       from  the  XSI Curses standard (which erroneously fails to
       describe the disabling of cuu).
        SVr4 の説明書は filter の動作をとてもあいまいな表現でしか
       記載していません。
        ここの記述は (cuu を無効化することについて誤って
       記述している) XSI Curses standard から修正したものです。


keyname

       The keyname function may return the names of  user-defined
       string  capabilities which are defined in the terminfo en-
       try via the -x option of tic.  This  implementation  auto-
       matically  assigns  at  run-time  keycodes to user-defined
       strings which begin  with  "k".   The  keycodes  start  at
       KEY_MAX,  but  are not guaranteed to be the same value for
       different runs because user-defined codes are merged  from
       all  terminal  descriptions  which  have been loaded.  The
       use_extended_names function controls whether this data  is
       loaded  when  the  terminal description is read by the li-
       brary.
        keyname 関数は、tic-x オプション経由で terminfo の
       収録項目に定義されているユーザ定義文字列機能の名前を返すことが
       あります。
        この実装は、実行時に "k" で始まるユーザ定義文字列に
       キーコードを自動的に割り当てます。
        キーコードは KEY_MAX で始まりますが、実行ごとに同じ値である
       ことは保証されません。これはユーザ定義のコードがすべての
       ロードされた端末記述からマージされるためです。
        use_extended_names 関数は、ライブラリが端末記述を読むときに
       このデータをロードするかどうかを制御します。


nofilter/use_tioctl

       The nofilter  and  use_tioctl  routines  are  specific  to
       ncurses.   They  were  not  supported on Version 7, BSD or
       System V implementations.  It is recommended that any code
       depending  on  ncurses  extensions  be  conditioned  using
       NCURSES_VERSION.
        nofilteruse_tioctl ルーチンは ncurses 固有です。
        これらは Version 7, BSD, System V の実装では
       サポートされていません。
        ncurses 拡張機能に依存するすべてのコードは、
       NCURSES_VERSION を使って条件付きとすることを推奨します。


putwin/getwin

       The putwin and getwin functions have several  issues  with
       portability:
        putwingetwin 関数は移植性に関して数個の問題があります。

       o   The  files  written and read by these functions use an
           implementation-specific format.  Although  the  format
           is  an obvious target for standardization, it has been
           overlooked.
       o   これらの関数が読み書きするファイルは実装依存の
           フォーマットを使います。
           ファイル・フォーマットは明らかに標準化の目標ですが、
           見過ごされてきました。

           Interestingly enough, according to the copyright dates
           in Solaris source, the functions (along with scr_init,
           etc.) originated with the  University  of  California,
           Berkeley  (in  1982) and were later (in 1988) incorpo-
           rated into SVr4.  Oddly, there are no  such  functions
           in the 4.3BSD curses sources.
           とても興味深いことに、Solaris ソースの著作権登録年によると
           これらの関数は (scr_init などと共に) カリフォルニア大学
           バークレー校 (1982年) に端を発し、後に SVr4 に
           組み込まれました (1988年)。
           奇妙なことに、4.3BSD curses のソースにはこのような関数は
           ありません。

       o   Most  implementations  simply  dump  the binary WINDOW
           structure to the file.   These  include  SVr4  curses,
           NetBSD  and  PDCurses,  as  well as older ncurses ver-
           sions.  This implementation (as  well  as  the  X/Open
           variant  of  Solaris  curses, dated 1995) uses textual
           dumps.
       o   多くの実装では単純に WINDOW 構造体のバイナリをファイルに
           ダンプ出力します。
           これには ncurses の古いバージョンとともに、SVr4 curses, 
           NetBSD, PDCurses が含まれます。
           この実装は (X/Open の変種である 1995年の Solaris curses 
           と同様に) テキスト形式のダンプを用いています。

           The implementations which use binary dumps use  block-
           I/O  (the fwrite and fread functions).  Those that use
           textual dumps use buffered-I/O.   A  few  applications
           may happen to write extra data in the file using these
           functions.  Doing that can run  into  problems  mixing
           block-  and buffered-I/O.  This implementation reduces
           the problem on writes by flushing the output.   Howev-
           er,  reading  from  a file written using mixed schemes
           may not be successful.
           バイナリ・ダンプを使う実装は、ブロック入出力を使います 
           (fwritefread 関数)。
           テキスト形式のダンプを使う実装は、バッファ付き入出力を
           使います。
           少数のアプリケーションはこれらの関数を使ってファイルに
           追加のデータを書き込むことがあります。
           それはブロック入出力とバッファ付き入出力を混用することで
           問題を引き起こす可能性があります。
           この実装では出力を一掃することで書き込み時の問題を減らして
           います。
           しかし、混合した方式を用いて書き込んだファイルからの
           読み込みは、成功しないかもしれません。


unctrl/wunctrl

       The XSI Curses standard, Issue  4  describes  these  func-
       tions.   It  states  that unctrl and wunctrl will return a
       null pointer if unsuccessful, but does not define any  er-
       ror conditions.  This implementation checks for three cas-
       es:
        これらの関数は XSI Curses standard, Issue 4 に記載されて
       います。
        これは unctrlwunctrl は失敗のときヌルポインタを返すと
       明示していますが、エラーの条件を何も定義していません。
        この実装は、次の 3 つの場合を調べます。

       o   the parameter is a 7-bit US-ASCII code.  This  is  the
           case that X/Open Curses documented.
       o   引数が 7 ビット US-ASCII コードの場合。
           これは X/Open Curses に書かれている場合です。

       o   the parameter is in the range 128-159, i.e., a C1 con-
           trol code.  If use_legacy_coding has been called  with
           a  2  parameter, unctrl returns the parameter, i.e., a
           one-character string with the parameter as  the  first
           character.   Otherwise,  it  returns "~@", "~A", etc.,
           analogous to "^@", "^A", C0 controls.
       o   引数が 128-159 の範囲、つまり C1 制御文字の場合。
           use_legacy_coding が引数 2 と共に呼び出された場合、
           unctrl は引数を返します。つまり引数を最初の文字とする 
           1 文字の文字列です。
           さもなければ、("^@", "^A",… など C0 制御文字に類似した) 
           "~@", "~A",… などを返します。

           X/Open Curses does not document whether unctrl can  be
           called  before  initializing curses.  This implementa-
           tion permits that, and returns the "~@", etc.,  values
           in that case.
           X/Open Curses は curses を初期化する前に unctrl を
           呼び出せるかどうかを記述していません。
           この実装ではそれを許しており、その場合には "~@",… などの
           値を返します。

       o   parameter  values  outside the 0 to 255 range.  unctrl
           returns a null pointer.
       o   引数が 0 から 255 の範囲外の場合。
           unctrl はヌルポインタを返します。

       The strings returned by unctrl in this implementation  are
       determined  at  compile time, showing C1 controls from the
       upper-128 codes with a `~' prefix rather than `^'.   Other
       implementations  have different conventions.  For example,
       they may show both sets of control  characters  with  `^',
       and  strip the parameter to 7 bits.  Or they may ignore C1
       controls and treat all of the upper-128  codes  as  print-
       able.  This implementation uses 8 bits but does not modify
       the string to reflect locale.  The use_legacy_coding func-
       tion allows the caller to change the output of unctrl.
        この実装では unctrl が返す文字列はコンパイル時に決定され、
       128 以上のコードから '^' 接頭辞でなく '~' 接頭辞を使って 
       C1 制御文字を表します。
        他の実装では仕様が異なっています。
        例えば、両方の制御文字の組を '^' を使って表すかも
       しれませんし、引数から 7 ビットを切り出すかもしれません。
        または、C1 制御文字を無視し、128 以上のコードはすべて
       印字可能として扱うかもしれません。
        この実装は 8 ビットを用いますが、ロケールを反映して文字列を
       修正することはしません。
        use_legacy_coding 関数は unctrl の出力を変更できるように
       します。

       Likewise,  the  meta  function allows the caller to change
       the output of keyname, i.e., it determines whether to  use
       the `M-' prefix for "meta" keys (codes in the range 128 to
       255).  Both use_legacy_coding and meta succeed only  after
       curses  is  initialized.   X/Open Curses does not document
       the treatment of codes 128 to 159.  When treating them  as
       "meta"  keys  (or if keyname is called before initializing
       curses),  this  implementation  returns  strings   "M-^@",
       "M-^A", etc.
        同様に、meta 関数は keyname の出力を変更できるようにします。
       つまりこれは "メタ" キー (128 から 255 のコード範囲) に対して 
       M- 接頭辞を使うかどうかを決定します。
        use_legacy_codingmeta も curses が初期化された後しか
       成功しません。
        X/Open Curses は 128 から 159 までのコードの扱いについて
       記述していません。
        これらを "メタ" キーとして扱うとき (または curses を初期化
       する前に keyname が呼ばれたとき)、この実装は "M-^@", "M-^A", 
       などの文字列を返します。


SEE ALSO 関連項目

       legacy_coding(3x), curses(3x), curs_initscr(3x), 
       curs_kernel(3x),  curs_scr_dump(3x),  curs_variables(3x),
       legacy_coding(3x). ←重複(訳注)



                                                          curs_util(3x)