"termios" --- POSIX スタイルの端末制御
**************************************

======================================================================

このモジュールでは端末 I/O 制御のための POSIX 準拠の関数呼び出しインタ
ーフェースを提供します。これら呼び出しのための完全な記述については、
Unix マニュアルページの *termios(3)* を参照してください。これは POSIX
*termios* 形式の端末制御をサポートしていてインストール時に有効にした
Unix のバージョンでのみ利用可能です。

利用可能な環境: Unix.

このモジュールの関数は全て、ファイル記述子 *fd* を最初の引数としてとり
ます。この値は、 "sys.stdin.fileno()" が返すような整数のファイル記述子
でも、 "sys.stdin" 自体のような *file object* でもかまいません。

このモジュールでは、ここで提供する関数を使うために必要なすべての定数も
定義しています。 定数の名前は C の対応する定数と同じです。 これらの端
末制御インターフェースの使い方については、システムのドキュメントを参照
してください。

このモジュールには、以下の関数が定義されています:

termios.tcgetattr(fd)

   Return a list containing the tty attributes for file descriptor
   *fd*, as follows: "[iflag, oflag, cflag, lflag, ispeed, ospeed,
   cc]" where *cc* is a list of the tty special characters (each a
   string of length 1, except the items with indices "VMIN" and
   "VTIME", which are integers when these fields are defined).  The
   interpretation of the flags and the speeds as well as the indexing
   in the *cc* array must be done using the symbolic constants defined
   in the "termios" module.

   termios.VMIN
   termios.VTIME

      Indices into the *cc* array controlling a non-canonical read:
      the minimum number of characters to read and the timeout in
      tenths of a second, respectively.

termios.tcsetattr(fd, when, attributes)

   ファイル記述子 *fd* の tty 属性を *attributes* に設定します。
   *attributes* は "tcgetattr()" が返すものと同じ形式のリストです。 属
   性を変更するタイミングは *when* 引数で指定します。

   termios.TCSANOW

      属性を直ちに変更します。

   termios.TCSADRAIN

      キューにある出力をすべて送信してから属性を変更します。

   termios.TCSAFLUSH

      キューにある出力をすべて送信し、キューにある入力をすべて破棄して
      から属性を変更します。

termios.tcsendbreak(fd, duration)

   ファイル記述子 *fd* にブレークを送信します。*duration* をゼロにする
   と、0.25〜0.5 秒間のブレークを送信します; *duration* の値がゼロでな
   い場合、その意味はシステム依存です。

termios.tcdrain(fd)

   ファイル記述子 *fd* に書き込まれた全ての出力が転送されるまで待ちま
   す。

termios.tcflush(fd, queue)

   ファイル記述子 *fd* にキューに入っているデータを破棄します。 どのキ
   ューかは *queue* セレクタで指定します: "TCIFLUSH" は入力キュー、
   "TCOFLUSH" は出力キュー、 "TCIOFLUSH" は両方のキューです。

   termios.TCIFLUSH
   termios.TCOFLUSH
   termios.TCIOFLUSH

      Values for the *queue* selector: the input queue, the output
      queue, or both queues, respectively.

termios.tcflow(fd, action)

   ファイル記述子 *fd* の入力または出力をサスペンドしたりレジュームし
   たりします。引数 *action* は出力をサスペンドする "TCOOFF" 、出力を
   レジュームする "TCOON" 、入力をサスペンドする "TCIOFF" 、入力をレジ
   ュームする "TCION" をとることができます。

   termios.TCOOFF
   termios.TCOON
   termios.TCIOFF
   termios.TCION

      Values for the *action* argument: suspend output, restart
      output, suspend input, or restart input, respectively.

termios.tcgetwinsize(fd)

   ファイル記述子 *fd* の tty ウィンドウサイズを表すタプル "(ws_row,
   ws_col)" を返します。 "termios.TIOCGWINSZ" または
   "termios.TIOCGSIZE" が必要です。

   Added in version 3.11.

   termios.TIOCGWINSZ
   termios.TIOCGSIZE

      "ioctl()" requests for querying the tty window size.  Not
      defined on all platforms; "tcgetwinsize()" requires at least one
      of them.

termios.tcsetwinsize(fd, winsize)

   ファイル記述子 *fd* の tty ウィンドウサイズを *winsize* に設定しま
   す。 *winsize* は "tcgetwinsize()" が返すものと同じ形式の、2 要素の
   タプル "(ws_row, ws_col)" です。 ("termios.TIOCGWINSZ",
   "termios.TIOCSWINSZ") と ("termios.TIOCGSIZE", "termios.TIOCSSIZE")
   のうち、少なくとも一方の組が定義されている必要があります。

   Added in version 3.11.

   termios.TIOCSWINSZ
   termios.TIOCSSIZE

      "ioctl()" requests for setting the tty window size.  Not defined
      on all platforms; see "tcsetwinsize()" for the required pairs.

参考:

  "tty" モジュール
     一般的な端末制御操作のための便利な関数。


使用例
======

以下はエコーバックを切った状態でパスワード入力を促す関数です。 何が起
きても元の tty 属性を正確に復元できるように、"tcgetattr()" を別々に呼
び出し、"try" ... "finally" 文を使う手法に注目してください。

   def getpass(prompt="Password: "):
       import termios, sys
       fd = sys.stdin.fileno()
       old = termios.tcgetattr(fd)
       new = termios.tcgetattr(fd)
       new[3] = new[3] & ~termios.ECHO          # lflags
       try:
           termios.tcsetattr(fd, termios.TCSADRAIN, new)
           passwd = input(prompt)
       finally:
           termios.tcsetattr(fd, termios.TCSADRAIN, old)
       return passwd
