release/man4/tty_ioctl.4

   1 .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
   2 .\" and Andries Brouwer <aeb@cwi.nl>.
   3 .\" Distributed under GPL.
   4 .\"
   5 .\" Japanese Version Copyright (c) 2004 Yuichi SATO
   6 .\"         all rights reserved.
   7 .\" Translated Sat Oct 16 06:08:24 JST 2004
   8 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
   9 .\"
  10 .TH TTY_IOCTL 4 2008-10-29 "Linux" "Linux Programmer's Manual"
  11 .SH 名前
  12 tty_ioctl \- 端末とシリアルラインの ioctl (入出力制御)
  13 .SH 書式
  14 .B "#include <termios.h>"
  15 .sp
  16 .BI "int ioctl(int " fd ", int " cmd ", ...);"
  17 .SH 説明
  18 端末とシリアルポートについての
  19 .BR ioctl (2)
  20 コールは、多くのコマンド引き数を受け付ける。
  21 多くがいろいろな型の 3 番目の引き数を必要とする。
  22 ここでは \fIargp\fP または \fIarg\fP と呼ぶ。
  23 .LP
  24 .I ioctl
  25 を使用すると移植性のないプログラムになる。
  26 可能な場合は、
  27 .BR termios (3)
  28 に記述されている POSIX インタフェースを使うこと。
  29 .SS 端末属性の取得と設定
  30 .TP
  31 .BI "TCGETS     struct termios *" argp
  32 .I "tcgetattr(fd, argp)"
  33 と同じ。
  34 .br
  35 現在のシリアルポートの設定を取得する。
  36 .TP
  37 .BI "TCSETS     const struct termios *" argp
  38 .I "tcsetattr(fd, TCSANOW, argp)"
  39 と同じ。
  40 .br
  41 現在のシリアルポートの設定を変更する。
  42 .TP
  43 .BI "TCSETSW    const struct termios *" argp
  44 .I "tcsetattr(fd, TCSADRAIN, argp)"
  45 と同じ。
  46 .br
  47 排出 (drain) を行うための出力バッファの使用を許可し、
  48 現在のシリアルポートの設定を変更する。
  49 .TP
  50 .BI "TCSETSF    const struct termios *" argp
  51 .I "tcsetattr(fd, TCSAFLUSH, argp)"
  52 と同じ。
  53 .br
  54 排出 (drain) を行うための出力バッファの使用を許可し、
  55 処理していない入力を破棄して、
  56 現在のシリアルポートの設定を変更する。
  57 .LP
  58 以下の 4 つの ioctl は
  59 .BR TCGETS ,
  60 .BR TCSETS ,
  61 .BR TCSETSW ,
  62 .B TCSETSF
  63 と似ている。
  64 ただし、
  65 .I "struct termios *"
  66 の代わりに
  67 .I "struct termio *"
  68 を取る。
  69 .TP
  70 .BI "TCGETA     struct termio *" argp
  71 .TP
  72 .BI "TCSETA     const struct termio *" argp
  73 .TP
  74 .BI "TCSETAW    const struct termio *" argp
  75 .TP
  76 .BI "TCSETAF    const struct termio *" argp
  77 .SS "termios 構造体のロック"
  78 端末の
  79 .I termios
  80 構造体はロックすることが可能である。
  81 このロック自体は
  82 .I termios
  83 構造体であり、
  84 0 でないビットまたはフィールドはロックされた値を示す。
  85 .TP
  86 .BI "TIOCGLCKTRMIOS     struct termios *" argp
  87 端末の
  88 .I termios
  89 構造体のロック状態を取得する。
  90 .TP
  91 .BI "TIOCSLCKTRMIOS     const struct termios *" argp
  92 端末の
  93 .I termios
  94 構造体のロック状態を設定する。
  95 root のみ (より正確には、
  96 .B CAP_SYS_ADMIN
  97 ケーパビリティを持つプロセス) がこれを実行できる。
  98 .SS ウィンドウサイズの取得と設定
  99 ウィンドウサイズはカーネル内に保持されるが、
 100 カーネルによって使用されない
 101 (仮想コンソールの場合は例外であり、新しいフォントを読み込んだ場合など、
 102 仮想端末のサイズが変更された場合、カーネルはウィンドウサイズを更新する)。
 103
 104 以下の定数と構造体は
 105 .I <sys/ioctl.h>
 106 で定義されている。
 107 .TP
 108 .BI "TIOCGWINSZ struct winsize *" argp
 109 ウィンドウサイズを取得する。
 110 .TP
 111 .BI "TIOCSWINSZ const struct winsize *" argp
 112 ウィンドウサイズを設定する。
 113 .LP
 114 これらの ioctl で使用される構造体は、以下のように定義される。
 115
 116 .in +4n
 117 .nf
 118 struct winsize {
 119     unsigned short ws_row;
 120     unsigned short ws_col;
 121     unsigned short ws_xpixel;   /* 未使用 */
 122     unsigned short ws_ypixel;   /* 未使用 */
 123 };
 124 .fi
 125 .in
 126
 127 ウィンドウサイズが変更された場合、
 128 フォアグラウンドプロセスグループに
 129 .B SIGWINCH
 130 シグナルが送られる。
 131 .SS "break の送信"
 132 .TP
 133 .BI "TCSBRK     int " arg
 134 .I "tcsendbreak(fd, arg)"
 135 と同じ。
 136 .br
 137 端末が非同期シリアルデータ転送を使用しており、
 138 .I arg
 139 が 0 の場合、0.25 から 0.5 秒の間に
 140 break (0 のビット列のストリーム) が送信される。
 141 端末が非同期シリアルデータ転送を使用している場合、
 142 break が送信されるか、この関数は何もせずに返る。
 143 .I arg
 144 が 0 以外の場合、何が起こるか分からない。
 145
 146 (SVr4, UnixWare, Solaris, Linux は、
 147 .I "tcsendbreak(fd,arg)"
 148 の
 149 .I arg
 150 が 0 以外の場合、
 151 .I "tcdrain(fd)"
 152 のように扱う。
 153 SunOS は
 154 .I arg
 155 を倍数として扱い、ビットのストリームを
 156 .I arg
 157 回送信する。
 158 .I arg
 159 が 0 の場合も同じ。
 160 DG/UX と AIX は、(0 以外の場合)
 161 .I arg
 162 をミリ秒単位の時間間隔として扱う。
 163 HP-UX は
 164 .I arg
 165 を無視する。)
 166 .TP
 167 .BI "TCSBRKP    int " arg
 168 いわゆる「POSIX 版」の
 169 .B TCSBRK
 170 である。
 171 これは 0 以外の
 172 .I arg
 173 を 1/10 秒単位の時間間隔として扱う。
 174 またドライバが break をサポートしていない場合は、何もしない。
 175 .TP
 176 .B "TIOCSBRK    void"
 177 break をオンにする。
 178 つまり 0 のビット列の送信を開始する。
 179 .TP
 180 .B "TIOCCBRK    void"
 181 break をオフにする。
 182 つまり 0 のビット列の送信を停止する。
 183 .SS ソフトウェアフロー制御
 184 .TP
 185 .BI "TCXONC     int " arg
 186 .I "tcflow(fd, arg)"
 187 と同じ。
 188 .br
 189 .BR tcflow (3)
 190 の引き数
 191 .BR TCOOFF ,
 192 .BR TCOON ,
 193 .BR TCIOFF ,
 194 .B TCION
 195 を参照すること。
 196 .SS "バッファのカウントと書き出し (flush)"
 197 .TP
 198 .BI "FIONREAD   int *" argp
 199 入力バッファにあるバイト数を取得する。
 200 .TP
 201 .BI "TIOCINQ    int *" argp
 202 .B FIONREAD
 203 と同じ。
 204 .TP
 205 .BI "TIOCOUTQ   int *" argp
 206 出力バッファにあるバイト数を取得する。
 207 .TP
 208 .BI "TCFLSH     int " arg
 209 .I "tcflush(fd, arg)"
 210 と同じ。
 211 .br
 212 .BR tcflush (3)
 213 の引き数
 214 .BR TCIFLUSH ,
 215 .BR TCOFLUSH ,
 216 .B TCIOFLUSH
 217 を参照すること。
 218 .SS 入力の偽装
 219 .TP
 220 .BI "TIOCSTI    const char *" argp
 221 指定されたバイトを入力キューに挿入する。
 222 .SS コンソール出力のリダイレクト
 223 .TP
 224 .B "TIOCCONS    void"
 225 .I /dev/console
 226 または
 227 .I /dev/tty0
 228 に送られる出力を、指定された端末リダイレクトする。
 229 指定された端末が疑似端末 (pseudoterminal) のマスタの場合、
 230 出力はスレーブに送られる。
 231 バージョン 2.6.10 より前の Linux では、出力がまだリダイレクトされて
 232 いなければ、誰でもリダイレクトを行うことができる。
 233 バージョン 2.6.10 以降では、root
 234 .RB ( CAP_SYS_ADMIN
 235 ケーパビリティを持つプロセス) だけがリダイレクトを行うことができる。
 236 出力がすでにリダイレクトされている場合は
 237 .B EBUSY
 238 が返されるが、
 239 .I /dev/console
 240 か
 241 .I /dev/tty0
 242 を指している
 243 .I fd
 244 に対してこの ioctl を使用することで、リダイレクトを止めることができる。
 245 .SS "端末の制御"
 246 .TP
 247 .BI "TIOCSCTTY  int " arg
 248 指定された端末を呼び出し元のプロセスの制御端末にする。
 249 呼び出し元のプロセスはセッションリーダでなければならず、
 250 かつ既に制御端末を持っていてはならない。
 251 この端末が既に他のセッショングループの制御端末である場合、
 252 ioctl は
 253 .B EPERM
 254 で失敗する。ただし呼び出したユーザが root で
 255 (より正確には
 256 .B CAP_SYS_ADMIN
 257 ケーパビリティを持っていて)、かつ
 258 .I arg
 259 が 1 である場合を除く。
 260 この場合、端末は盗まれ (stolen)、
 261 この端末を制御端末としていた全てのプロセスは端末を失う。
 262 .TP
 263 .B TIOCNOTTY    void
 264 指定された端末が呼び出し元のプロセスの制御端末である場合、
 265 この制御端末を放棄する。
 266 プロセスがセッションリーダの場合、
 267 フォアグラウンドプロセスグループに
 268 .B SIGHUP
 269 と
 270 .B SIGCONT
 271 を送り、カレントセッションの全てのプロセスは制御端末を失う。
 272 .SS "グループ ID とセッション ID の処理"
 273 .TP
 274 .BI "TIOCGPGRP  pid_t *" argp
 275 成功した場合、
 276 .I "*argp = tcgetpgrp(fd)"
 277 と同じ。
 278 .br
 279 この端末上のフォアグラウンドプロセスのプロセスグループ ID を取得する。
 280 .TP
 281 .BI "TIOCSPGRP  const pid_t *" argp
 282 .I "tcsetpgrp(fd, *argp)"
 283 と同じ。
 284 .br
 285 この端末のフォアグラウンドプロセスのグループ ID を設定する。
 286 .TP
 287 .BI "TIOCGSID   pid_t *" argp
 288 指定された端末のセッション ID を取得する。
 289 端末がマスタ疑似端末または制御端末でない場合は、
 290 .B ENOTTY
 291 で失敗する。
 292 奇妙だ。
 293 .SS 排他モード
 294 .TP
 295 .B "TIOCEXCL    void"
 296 端末を排他モードにする。
 297 端末に対して、これ以降の
 298 .BR open (2)
 299 操作を禁止する。
 300 (root 以外の場合、つまり
 301 .B CAP_SYS_ADMIN
 302 ケーパビリティを持たないプロセスの場合、これ以降の
 303 .BR open (2)
 304 は
 305 .B EBUSY
 306 で失敗する。)
 307 .TP
 308 .B "TIOCNXCL    void"
 309 排他モードを無効にする。
 310 .SS "ライン制御 (line discipline)"
 311 .TP
 312 .BI "TIOCGETD   int *" argp
 313 端末のライン制御の情報を取得する。
 314 .TP
 315 .BI "TIOCSETD   const int *" argp
 316 端末のライン制御の情報を設定する。
 317 .SS "疑似端末の ioctl"
 318 .TP
 319 .BI "TIOCPKT    const int *" argp
 320 パケットモードを有効
 321 .RI (* argp
 322 が 0 以外の場合) または無効にする。
 323 疑似端末のマスタ側にのみ適用できる (それ以外の場合は
 324 .B ENOTTY
 325 を返す)。
 326 パケットモードでは、その後に実行される
 327 .BR read (2)
 328 は、値が 0 以外の 1 つの制御バイトを含むパケットか、
 329 値が 0 の 1 バイト (\(aq\\0\(aq) に疑似端末のスレーブ側で書き込まれた
 330 データが続くパケットを返す。
 331 最初のバイトが
 332 .B TIOCPKT_DATA
 333 (0) でない場合、以下のビットの 1 つ以上を OR したものである:
 334
 335 .nf
 336 TIOCPKT_FLUSHREAD   端末の読み込みキューがフラッシュ (flush) される。
 337 TIOCPKT_FLUSHWRITE  端末の書き出しキューがフラッシュされる。
 338 TIOCPKT_STOP        端末への出力が停止される。
 339 TIOCPKT_START       端末への出力が再開される。
 340 TIOCPKT_DOSTOP      開始文字と終了文字が \fB^S\fP/\fB^Q\fP である。
 341 TIOCPKT_NOSTOP      開始文字と終了文字が \fB^S\fP/\fB^Q\fP でない。
 342 .fi
 343
 344 このモードが使われている場合、
 345 制御状態情報の存在がマスタ側から読み込めるかは、
 346 例外的な条件で
 347 .BR select (2)
 348 を使うことにより知ることができる。
 349
 350 このモードは
 351 .BR rlogin (1)
 352 と
 353 .BR rlogind (8)
 354 で使われ、リモートエコーのリモートログインと
 355 ローカルでの \fB^S\fP/\fB^Q\fP フロー制御のリモートログインを実装している。
 356
 357 BSD の ioctl である
 358 .BR TIOCSTOP ,
 359 .BR TIOCSTART ,
 360 .BR TIOCUCNTL ,
 361 .B TIOCREMOTE
 362 は、Linux では実装されていない。
 363 .SS モデム制御
 364 .TP
 365 .BI "TIOCMGET   int *" argp
 366 モデムビット列の状態を取得する。
 367 .TP
 368 .BI "TIOCMSET   const int *" argp
 369 モデムビット列の状態を設定する。
 370 .TP
 371 .BI "TIOCMBIC   const int *" argp
 372 指定されたモデムビット列をクリアする。
 373 .TP
 374 .BI "TIOCMBIS   const int *" argp
 375 指定されたモデムビット列を設定する。
 376 .LP
 377 これらの 4 つの ioctl で使われるビットは以下の通り:
 378
 379 .nf
 380 TIOCM_LE        DSR (data set ready/line enable)
 381 TIOCM_DTR       DTR (data terminal ready)
 382 TIOCM_RTS       RTS (request to send)
 383 TIOCM_ST        Secondary TXD (transmit)
 384 TIOCM_SR        Secondary RXD (receive)
 385 TIOCM_CTS       CTS (clear to send)
 386 TIOCM_CAR       DCD (data carrier detect)
 387 TIOCM_CD         TIOCM_CAR を参照。
 388 TIOCM_RNG       RNG (ring)
 389 TIOCM_RI         TIOCM_RNG を参照。
 390 TIOCM_DSR       DSR (data set ready)
 391 .fi
 392 .SS "回線をローカルとしてマークする"
 393 .TP
 394 .BI "TIOCGSOFTCAR       int *" argp
 395 ("ソフトウェアキャリアフラグの取得")
 396 .I termios
 397 構造体の c_cflag フィールドの
 398 .B CLOCAL
 399 フラグの状態を取得する。
 400 .TP
 401 .BI "TIOCSSOFTCAR       const int *" argp
 402 ("ソフトウェアキャリアフラグの設定")
 403 .RI * argp
 404 が 0 以外の場合、
 405 .I termios
 406 構造体の
 407 .B CLOCAL
 408 フラグを設定する。
 409 0 の場合はクリアする。
 410 .LP
 411 ラインの
 412 .B CLOCAL
 413 フラグがオフの場合、
 414 ハードウェアキャリア検出 (hardware carrier detect, DCD) シグナルが重要であり、
 415 .B O_NONBLOCK
 416 フラグが指定されない限り、対応する端末の
 417 .BR open (2)
 418 は DCD が示されるまでブロックされる。
 419 .B CLOCAL
 420 が設定されている場合、
 421 ラインは常に DCD が示されているかのように動作する。
 422 ソフトウェアキャリアフラグは、ローカルデバイスでは通常はオンになっており、
 423 モデムのラインではオフになっている。
 424 .SS "Linux 固有の ioctl"
 425 .B TIOCLINUX
 426 ioctl については、
 427 .BR console_ioctl (4)
 428 を参照すること。
 429 .SS カーネルデバッギング
 430 .B "#include <linux/tty.h>"
 431 .TP
 432 .BI "TIOCTTYGSTRUCT     struct tty_struct *" argp
 433 .I fd
 434 に対応する
 435 .I tty_struct
 436 を取得する。
 437 .\" .SS "シリアル情報"
 438 .\" .BR "#include <linux/serial.h>"
 439 .\" .sp
 440 .\" .TP
 441 .\" .BI "TIOCGSERIAL    struct serial_struct *" argp
 442 .\" シリアル情報を取得する。
 443 .\" .TP
 444 .\" .BI "TIOCSSERIAL    const struct serial_struct *" argp
 445 .\" シリアル情報を設定する。
 446 .SH 返り値
 447 .BR ioctl (2)
 448 システムコールは、成功した場合は 0 を返す。
 449 エラーの場合は \-1 を返し、
 450 .I errno
 451 を適切に設定する。
 452 .SH エラー
 453 .TP
 454 .B EINVAL
 455 不正なコマンド引き数である。
 456 .TP
 457 .B ENOIOCTLCMD
 458 不明なコマンドである。
 459 .TP
 460 .B ENOTTY
 461 .I fd
 462 が不適切である。
 463 .TP
 464 .B EPERM
 465 権限が不足している。
 466 .SH 例
 467 シリアルポートの DTR の状態をチェックする。
 468
 469 .nf
 470 #include <termios.h>
 471 #include <fcntl.h>
 472 #include <sys/ioctl.h>
 473
 474 int
 475 main(void)
 476 {
 477     int fd, serial;
 478
 479     fd = open("/dev/ttyS0", O_RDONLY);
 480     ioctl(fd, TIOCMGET, &serial);
 481     if (serial & TIOCM_DTR)
 482         puts("TIOCM_DTR が設定されていない。");
 483     else
 484         puts("TIOCM_DTR が設定されている。");
 485     close(fd);
 486 }
 487 .fi
 488 .SH 関連項目
 489 .BR ioctl (2),
 490 .BR termios (3),
 491 .BR console_ioctl (4),
 492 .BR pty (7)
 493 .\"
 494 .\" FIONBIO                     const int *
 495 .\" FIONCLEX                    void
 496 .\" FIOCLEX                     void
 497 .\" FIOASYNC                    const int *
 498 .\" serial.c より:
 499 .\" TIOCSERCONFIG               void
 500 .\" TIOCSERGWILD                int *
 501 .\" TIOCSERSWILD                const int *
 502 .\" TIOCSERGSTRUCT              struct async_struct *
 503 .\" TIOCSERGETLSR               int *
 504 .\" TIOCSERGETMULTI             struct serial_multiport_struct *
 505 .\" TIOCSERSETMULTI             const struct serial_multiport_struct *
 506 .\" TIOCGSERIAL, TIOCSSERIAL (上記を参照)