1 TERMIOX(7I)                     Ioctl Requests                     TERMIOX(7I)
   2 
   3 NAME
   4      termiox - extended general terminal interface
   5 
   6 DESCRIPTION
   7      The extended general terminal interface supplements the termio(7I)
   8      general terminal interface by adding support for asynchronous hardware
   9      flow control, isochronous flow control and clock modes, and local
  10      implementations of additional asynchronous features.  Some systems may
  11      not support all of these capabilities because of either hardware or
  12      software limitations.  Other systems may not permit certain functions to
  13      be disabled.  In these cases the appropriate bits will be ignored.  See
  14      <sys/termiox.h> for your system to   find out which capabilities are
  15      supported.
  16 
  17    Hardware Flow Control Modes
  18      Hardware flow control supplements the termio(7I) IXON, IXOFF, and IXANY
  19      character flow control.  Character flow control occurs when one device
  20      controls the data transfer of another device by the insertion of control
  21      characters in the data stream between devices.  Hardware flow control
  22      occurs when one device controls the data transfer of another device using
  23      electrical control signals on wires (circuits) of the asynchronous
  24      interface.  Isochronous hardware flow control occurs when one device
  25      controls the data transfer of another device by asserting or removing the
  26      transmit clock signals of that device.  Character flow control and
  27      hardware flow control may be simultaneously set.
  28 
  29      In asynchronous, full duplex applications, the use of the Electronic
  30      Industries Association's EIA-232-D Request To Send (RTS) and Clear To
  31      Send (CTS) circuits is the preferred method of hardware flow control.  An
  32      interface to other hardware flow control methods is included to provide a
  33      standard interface to these existing methods.
  34 
  35      The EIA-232-D standard specified only unidirectional hardware flow
  36      control -- the Data Circuit-terminating Equipment or Data Communications
  37      Equipment (DCE) indicates to the Data Terminal Equipment (DTE) to stop
  38      transmitting data.  The termiox interface allows both unidirectional and
  39      bidirectional hardware flow control; when bidirectional flow control is
  40      enabled, either the DCE or DTE can indicate to each other to stop
  41      transmitting data across the interface.  Note: It is assumed that the
  42      asynchronous port is configured as a DTE.  If the connected device is
  43      also a DTE and not a DCE, then DTE to DTE (for example, terminal or
  44      printer connected to computer) hardware flow control is possible by using
  45      a null modem to interconnect the appropriate data and control circuits.
  46 
  47    Clock Modes
  48      Isochronous communication is a variation of asynchronous communication
  49      whereby two communicating devices may provide transmit and/or receive
  50      clock signals to one another.  Incoming clock signals can be taken from
  51      the baud rate generator on the local isochronous port controller, from
  52      CCITT V.24 circuit 114, Transmitter Signal Element Timing - DCE source
  53      (EIA-232-D pin 15), or from CITT V.24 circuit 115, Receiver Signal
  54      Element Timing - DCE source (EIA-232-D pin 17).  Outgoing clock signals
  55      can be sent on CCITT V.24 circuit 113, Transmitter Signal Element Timing
  56      - DTE source (EIA-232-D pin 24), on CCITT V.24 circuit 128, Receiver
  57      Signal Element Timing - DTE source (no EIA-232-D pin), or not sent at
  58      all.
  59 
  60      In terms of clock modes, traditional asynchronous communication is
  61      implemented simply by using the local baud rate generator as the incoming
  62      transmit and receive clock source and not outputting any clock signals.
  63 
  64    Terminal Parameters
  65      The parameters that control the behavior of devices providing the termiox
  66      interface are specified by the termiox structure defined in the
  67      <sys/termiox.h> header.  Several ioctl(2) system calls that fetch or
  68      change these parameters use this structure:
  69 
  70        #define NFF     5
  71        struct termiox  {
  72                unsigned short  x_hflag;       /* hardware flow control modes */
  73                unsigned short  x_cflag;       /* clock modes */
  74                unsigned short  x_rflag[NFF];  /* reserved modes */
  75                unsigned short  x_sflag;       /* spare local modes */
  76        };
  77 
  78      The x_hflag field describes hardware flow control modes:
  79 
  80      RTSXOFF    0000001    Enable RTS hardware flow control on input.
  81      CTSXON     0000002    Enable CTS hardware flow control on output.
  82      DTRXOFF    0000004    Enable DTR hardware flow control on input.
  83      CDXON      0000010    Enable CD hardware flow control on output.
  84      ISXOFF     0000020    Enable isochronous hardware flow control on input.
  85 
  86      The EIA-232-D DTR and CD circuits are used to establish a connection
  87      between two systems.  The RTS circuit is also used to establish a
  88      connection with a modem.  Thus, both DTR and RTS are activated when an
  89      asynchronous port is opened.  If DTR is used for hardware flow control,
  90      then RTS must be used for connectivity.  If CD is used for hardware flow
  91      control, then CTS must be used for connectivity.  Thus, RTS and DTR (or
  92      CTS and CD) cannot both be used for hardware flow control at the same
  93      time.  Other mutual exclusions may apply, such as the simultaneous
  94      setting of the termio(7I) HUPCL and the termiox DTRXOFF bits, which use
  95      the DTE ready line for different functions.
  96 
  97      Variations of different hardware flow control methods may be selected by
  98      setting the appropriate bits.  For example, bidirectional RTS/CTS flow
  99      control is selected by setting both the RTSXOFF and CTSXON bits and
 100      bidirectional DTR/CTS flow control is selected by setting both the
 101      DTRXOFF and CTSXON.  Modem control or unidirectional CTS hardware flow
 102      control is selected by setting only the CTSXON bit.
 103 
 104      As previously mentioned, it is assumed that the local asynchronous port
 105      (for example, computer) is configured as a DTE.  If the connected device
 106      (for example, printer) is also a DTE, it is assumed that the device is
 107      connected to the computer's asynchronous port using a null modem that
 108      swaps control circuits (typically RTS and CTS).  The connected DTE drives
 109      RTS and the null modem swaps RTS and CTS so that the remote RTS is
 110      received as CTS by the local DTE.  In the case that CTSXON is set for
 111      hardware flow control, printer's lowering of its RTS would cause CTS seen
 112      by the computer to be lowered.  Output to the printer is suspended until
 113      the printer's raising of its RTS, which would cause CTS seen by the
 114      computer to be raised.
 115 
 116      If RTSXOFF is set, the Request To Send (RTS) circuit (line) will be
 117      raised, and if the asynchronous port needs to have its input stopped, it
 118      will lower the Request To Send (RTS) line.  If the RTS line is lowered,
 119      it is assumed that the connected device will stop its output until RTS is
 120      raised.
 121 
 122      If CTSXON is set, output will occur only if the Clear To Send (CTS)
 123      circuit (line) is raised by the connected device.  If the CTS line is
 124      lowered by the connected device, output is suspended until CTS is raised.
 125 
 126      If DTRXOFF is set, the DTE Ready (DTR) circuit (line) will be raised, and
 127      if the asynchronous port needs to have its input stopped, it will lower
 128      the DTE Ready (DTR) line.  If the DTR line is lowered, it is assumed that
 129      the connected device will stop its output until DTR is raised.
 130 
 131      If CDXON is set, output will occur only if the Received Line Signal
 132      Detector (CD) circuit (line) is raised by the connected device.  If the
 133      CD line is lowered by the connected device, output is suspended until CD
 134      is raised.
 135 
 136      If ISXOFF is set, and if the isochronous port needs to have its input
 137      stopped, it will stop the outgoing clock signal.  It is assumed that the
 138      connected device is using this clock signal to create its output.
 139      Transit and receive clock sources are programmed using the x_cflag
 140      fields.  If the port is not programmed for external clock generation,
 141      ISXOFF is ignored.  Output isochronous flow control is supported by
 142      appropriate clock source programming using the x_cflag field and enabled
 143      at the remote connected device.
 144 
 145      The x_cflag field specifies the system treatment of clock modes.
 146 
 147      XMTCLK       0000007     Transmit clock source:
 148      XCIBRG       0000000     Get transmit clock from internal baud rate
 149                               generator.
 150      XCTSET       0000001     Get transmit clock from transmitter signal
 151                               element timing (DCE source) lead, CCITT V.24
 152                               circuit 114, EIA-232-D pin 15.
 153      XCRSET       0000002     Get transmit clock from receiver signal element
 154                               timing (DCE source) lead, CCITT V.4 circuit 115,
 155                               EIA-232-D pin 17."
 156      RCVCLK       0000070     Receive clock source:
 157      RCIBRG       0000000     Get receive clock from internal baud rate
 158                               generator.
 159      RCTSET       0000010     Get receive clock from transmitter signal
 160                               element timing (DCE source) lead, CCITT V.24
 161                               circuit 114, EIA-232-D pin 15.
 162      RCRSET       0000020     Get receive clock from receiver signal element
 163                               timing (DCE source) lead, CCITT V.24 circuit
 164                               115, EIA-232-D pin 17.
 165      TSETCLK      0000700     Transmitter signal element timing (DTE source)
 166                               lead, CCITT V.24 circuit 113, EIA-232-D pin 24,
 167                               clock source:
 168      TSETCOFF     0000000     TSET clock not provided.
 169      TSETCRBRG    0000100     Output receive baud rate generator on circuit
 170                               113.
 171      TSETCTBRG    0000200     Output transmit baud rate generator on circuit
 172                               113
 173      TSETCTSET    0000300     Output transmitter signal element timing (DCE
 174                               source) on circuit 113.
 175      TSETCRSET    0000400     Output receiver signal element timing (DCE
 176                               source) on circuit 113.
 177      RSETCLK      0007000     Receiver signal element timing (DTE source)
 178                               lead, CCITT V.24 circuit 128, no EIA-232-D pin,
 179                               clock source:
 180      RSETCOFF     0000000     RSET clock not provided.
 181      RSETCRBRG    0001000     Output receive baud rate generator on circuit
 182                               128.
 183      RSETCTBRG    0002000     Output transmit baud rate generator on circuit
 184                               128.
 185      RSETCTSET    0003000     Output transmitter signal element timing (DCE
 186                               source) on circuit 128.
 187      RSETCRSET    0004000     Output receiver signal element timing (DCE) on
 188                               circuit 128.
 189 
 190      If the XMTCLK field has a value of XCIBRG the transmit clock is taken
 191      from the hardware internal baud rate generator, as in normal asynchronous
 192      transmission.  If XMTCLK = XCTSET the transmit clock is taken from the
 193      Transmitter Signal Element Timing (DCE source) circuit.  If XMTCLK =
 194      XCRSET the transmit clock is taken from the Receiver Signal Element
 195      Timing (DCE source) circuit.
 196 
 197      If the RCVCLK field has a value of RCIBRG, the receive clock is taken
 198      from the hardware Internal Baud Rate Generator, as in normal asynchronous
 199      transmission.  If RCVCLK = RCTSET the receive clock is taken from the
 200      Transmitter Signal Element Timing (DCE source) circuit.  If RCVCLK =
 201      RCRSET the receive clock is taken from the Receiver Signal Element Timing
 202      (DCE source) circuit.
 203 
 204      If the TSETCLK field has a value of TSETCOFF the Transmitter Signal
 205      Element Timing (DTE source) circuit is not driven.  If TSETCLK =
 206      TSETCRBRG the Transmitter Signal Element Timing (DTE source) circuit is
 207      driven by the Receive Baud Rate Generator.  If TSETCLK = TSETCTBRG the
 208      Transmitter Signal Element Timing (DTE source) circuit is driven by the
 209      Transmit Baud Rate Generator.  If TSETCLK = TSETCTSET the Transmitter
 210      Signal Element Timing (DTE source) circuit is driven by the Transmitter
 211      Signal Element Timing (DCE source).  If TSETCLK = TSETCRBRG the
 212      Transmitter Signal Element Timing (DTE source) circuit is driven by the
 213      Receiver Signal Element Timing (DCE source).
 214 
 215      If the RSETCLK field has a value of RSETCOFF the Receiver Signal Element
 216      Timing (DTE source) circuit is not driven.  If RSETCLK = RSETCRBRG the
 217      Receiver Signal Element Timing (DTE source) circuit is driven by the
 218      Receive Baud Rate Generator.  If RSETCLK = RSETCTBRG the Receiver Signal
 219      Element Timing (DTE source) circuit is driven by the Transmit Baud Rate
 220      Generator.  If RSETCLK = RSETCTSET the Receiver Signal Element Timing
 221      (DTE source) circuit is driven by the Transmitter Signal Element Timing
 222      (DCE source).  If RSETCLK = RSETCRBRG the Receiver Signal Element Timing
 223      (DTE source) circuit is driven by the Receiver Signal Element Timing (DCE
 224      source).
 225 
 226      The x_rflag is reserved for future interface definitions and should not
 227      be used by any implementations.  The x_sflag may be used by local
 228      implementations wishing to customize their terminal interface using the
 229      termiox ioctl system calls.
 230 
 231 IOCTLS
 232      The ioctl(2) system calls have the form:
 233 
 234        struct termiox *arg;
 235        ioctl(fildes, command, arg);
 236 
 237      The commands using this form are:
 238 
 239      TCGETX   The argument is a pointer to a termiox structure.  The current
 240               terminal parameters are fetched and stored into that structure.
 241 
 242      TCSETX   The argument is a pointer to a termiox structure.  The current
 243               terminal parameters are set from the values stored in that
 244               structure.  The change is immediate.
 245 
 246      TCSETXW  The argument is a pointer to a termiox structure.  The current
 247               terminal parameters are set from the values stored in that
 248               structure.  The change occurs after all characters queued for
 249               output have been transmitted.  This form should be used when
 250               changing parameters that will affect output.
 251 
 252      TCSETXF  The argument is a pointer to a termiox structure.  The current
 253               terminal parameters are set from the values stored in that
 254               structure.  The change occurs after all characters queued for
 255               output have been transmitted; all characters queued for input
 256               are discarded and then the change occurs.
 257 
 258 FILES
 259      /dev/*
 260 
 261 SEE ALSO
 262      stty(1), ioctl(2), termio(7I)
 263 
 264 NOTES
 265      The termiox(7I) system call is provided for compatibility with previous
 266      releases and its use is discouraged.  Instead, the termio(7I) system call
 267      is recommended.  See termio(7I) for usage information.
 268 
 269 illumos                        October 29, 2017                        illumos