SIO_$INTRO Domain/OS SIO_$INTRO
NAME
intro - controlling serial I/O lines
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/sio.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/sio.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/sio.ins.ftn'
DESCRIPTION
The calls are the program interface to the serial I/O (SIO) lines. They
can control and monitor the state of an RS-232 port, and modify the
stream connections to it. The file system interface to the SIO lines are
named /dev/sion where n is some integer.
There are only two sio_$ calls.
sio_$control set serial line options
sio_$inquire get serial line options
Constants
sio_$50
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$75
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$110
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$134
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$150
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$300
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$600
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$1200
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$2000
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$2400
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$3600
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$4800
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$7200
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$9600
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$19200
A baud rate value for the sio_$speed and sio_$speed_force options.
sio_$even_parity
A possible value for the sio_$parity option, denoting even parity.
sio_$max_line
The highest SIO line number supported.
sio_$no_parity
A possible value for the sio_$parity option, denoting no parity.
sio_$odd_parity
A possible value for the sio_$parity option, denoting odd parity.
sio_$stop_1
A stop bit value for the sio_$stop_bits option.
sio_$stop_1_point_5
A stop bit value for the sio_$stop_bits option.
sio_$stop_2
A stop bit value for the sio_$stop_bits option.
sio_$5bpc
A possible value for the sio_$bits_per_char option, denoting five
bits per character.
sio_$6bpc
A possible value for the sio_$bits_per_char option, denoting six
bits per character.
sio_$7bpc
A possible value for the sio_$bits_per_char option, denoting seven
bits per character.
sio_$8bpc
A possible value for the sio_$bits_per_char option, denoting eight
bits per character.
Data Types
sio_$err_enables_t
A small set of enabled SIO errors. It can assume a combination of
the following values:
sio_$check_parity
Check for received parity errors.
sio_$check_framing
Check for received framing errors.
sio_$check_dcd_change
Check for when the Data Carrier Detect (DCD) line changes
state.
sio_$check_cts_change
Check for when the Clear To Send (CTS) line changes state.
sio_$err_possibilities_t
A small set of errors to report during read calls on an SIO line.
It can assume a combination of the following values:
sio_$check_parity
Report parity errors.
sio_$check_framing
Report framing errors. Framing errors are reported by default.
sio_$check_dcd_change
Report DCD line state changes.
sio_$check_cts_change
Report CTS line state changes.
sio_$line_t
An SIO line number between 0 and sio_$max_line.
sio_$opt_t
An enumerated type for specifying an SIO option. It takes one of
the following values:
sio_$bits_per_char
The number of bits per character. This option can have one of
the following values:
sio_$5bpc
Five bits per character.
sio_$6bpc
Six bits per character.
sio_$7bpc
Seven bits per character.
sio_$8bpc
Eight bits per character.
sio_$bp_enable
This option is a Boolean value that enables or disables
interpretation of control codes from a bit pad. If true, bit
pad control code interpretation is enabled. If false, bit pad
control code interpretation is disabled. The default value is
false.
sio_$cts
This option is a Boolean value that reflects the state of the
Clear to Send (CTS) line. The value of this option cannot be
changed with sio_$control.
sio_$cts_enable
This option is a Boolean value that specifies whether the CTS
line will be used to inhibit transmission. If true, then
transmission is inhibited when CTS is false. If false, the CTS
line does not inhibit transmission.
sio_$dcd
This option is a Boolean value that reflects the state of the
Data Carrier Detect (DCD) line. The value of this option can-
not be changed with sio_$control.
sio_$dcd_enable
This option is a Boolean value that specifies whether a DCD
line transition will generate a fault_$stop fault. If true,
then a DCD line transition from true to false generates a
fault. If false, a DCD line transition does not generate a
fault.
sio_$drain_out
This option is a Boolean value that specifies whether write
calls on the SIO line should wait until all characters in the
output buffer are transmitted before returning. If true, the
write call waits. If false, the write call doesn't wait. The
default is false.
sio_$dtr
This option is a Boolean value that sets the state of the Data
Terminal Ready (DTR) line.
sio_$eofchr
The value of this option is the end-of-file (EOF) character.
It takes a character value, and the default is CTRL/Z.
sio_$erase
The value of this option is the erase character. It takes a
character value, and the default is CTRL/H.
sio_$err_enable
The value of this option is a small set of type
sio_$err_possibilities_t that defines the errors that can be
reported by read calls on an SIO line. It can be any combina-
tion of the following values:
sio_$check_parity
Report parity errors.
sio_$check_framing
Report framing errors. Framing errors are reported by
default.
sio_$check_dcd_change
Report DCD line state changes.
sio_$check_cts_change
Report CTS line state changes.
sio_$flush_in
This option is a Boolean value that specifies whether to flush
the input buffer of an SIO line. If true, the input buffer is
flushed. If false, the input buffer is not flushed. The
default is false.
sio_$flush_out
This option is a Boolean value that specifies whether to flush
the output buffer of an SIO line. If true, the output buffer
is flushed. If false, the output buffer is not flushed. The
default is false.
sio_$host_sync
This option is a Boolean value that enables or disables host
synchronization. If true, the node sends XOFF (CTRL/S) when
its input buffer is full, and sends XON (CTRL/Q) when it is
again ready to receive data. If false, the node does not use
XON/XOFF synchronization. The default is true.
sio_$hup_close
This option is a Boolean value that specifies whether the SIO
line should "hang up" when the last stream on it is closed. If
true, the node drops the Data Terminal Ready (DTR) line for
approximately three-fourths of a second when the last stream on
it is closed. If false, the node does not hang up.
sio_$input_sync
This option is a Boolean value that enables or disables input
synchronization. If true, the node honors incoming XON and
XOFF requests. If false, the node ignores incoming XON/XOFF
signals. The default is false.
sio_$int_enable
This option is a Boolean value that enables or disables inter-
rupts from the calling process. If true, the SIO line honors
interrupts from the calling process. If false, the SIO line
ignores interrupts from the calling process.
sio_$intchr
The value of this option is the interrupt character. It takes
a character value, and the default is CTRL/C.
sio_$kill
The value of this option is the kill character. It takes a
character value, and the default is CTRL/X.
sio_$line
This value of this option is the SIO line number, an integer
from 0 to sio_$max_line. The value of this option cannot be
changed with sio_$control.
sio_$nlc_delay
The value of this option is the time delay in milliseconds fol-
lowing transmission of a line feed character, to allow for car-
riage motion or scrolling time, and so on. The default is 0.
sio_$no_NL
This option is a Boolean value that specifies whether a newline
character is transmitted as a carriage-return line-feed
sequence or as a raw newline character. If true, newlines are
transmitted as is. If false, newlines are transmitted as
carriage-return line-feed sequences. The default is false.
sio_$no_echo
This option is a Boolean value that specifies whether input
characters are echoed back in the output. If true, input char-
acters are not echoed. If false, input characters are echoed
back to the sender. The default is false.
sio_$parity
The value of this option is the parity used by the SIO line.
It can take any one of the following values:
sio_$even_parity
Even parity.
sio_$no_parity
No parity.
sio_$odd_parity
Odd parity.
If the parity is even or odd, then one bit is added to each
character to enforce the chosen parity. If there are fewer
than eight bits per character, the parity bit is delivered with
the data in raw mode, but is stripped in cooked mode.
sio_$quit_enable
This option is a Boolean value that specifies whether the node
will respond to a quit character or break condition by inter-
rupting the calling process. If true, a quit or break gen-
erates a quit fault. If false, a quit or break is ignored.
The default is false. (In raw mode, break and quit are the
only ways to generate a quit fault.)
sio_$quitchr
The value of this option is the quit character. It takes a
character value, and the default is CTRL/].
sio_$raw
This option is a Boolean value that determines whether the line
is in raw or cooked mode. If true, the line is in raw mode and
each read returns all bytes received since the last call
without any interpretation. If false, the line is in cooked
mode and control codes are interpreted. The default value is
false.
The input buffer is flushed whenever sio_$raw changes value.
sio_$raw_nl
This option is a Boolean value that specifies whether a newline
character is transmitted as a carriage-return line-feed
sequence or as a raw newline character when the line is in raw
mode. If true, newlines are transmitted as is while in raw
mode. If false, newlines are transmitted as carriage-return
line-feed sequences while in raw mode. The default is false.
sio_$rts
This option is a Boolean value that determines the state of the
Request To Send (RTS) line. The default is true.
sio_$rts_enable
This option is a Boolean value that enables or disables the RTS
line. If true, the RTS line is used with the CTS line for data
flow control. For flow control to work, the CTS line must also
be enabled. If false, no RTS/CTS flow control is provided.
The default is false.
sio_$send_break
The value of this option is the duration of a break condition
on the SIO line, in milliseconds. A reasonable value for the
sio_$send_break option is 200. A value other than 0 causes a
break condition.
sio_$speed
The value of this option is the baud rate of the SIO line. It
can have any of the following values: sio_$50, sio_$75,
sio_$110, sio_$134, sio_$150, sio_$300, sio_$600, sio_$1200,
sio_$2000, sio_$2400, sio_$3600, sio_$4800, sio_$7200,
sio_$9600, or sio_$19200. The default is sio_$9600.
sio_$speed_force
The value of this option is the baud rate of a partnered SIO
line. The baud rate is forced to the value of this option,
even if it is incompatible with the rate of the line's partner.
If the value of sio_$speed_force is incompatible with the speed
of the partnered line, the partnered line is forced to the
default speed of sio_$9600. This option can have any of the
following values: sio_$50, sio_$75, sio_$110, sio_$134,
sio_$150, sio_$300, sio_$600, sio_$1200, sio_$2000, sio_$2400,
sio_$3600, sio_$4800, sio_$7200, sio_$9600, or sio_$19200.
sio_$stop_bits
The value of this option is the number of stop bits used by the
SIO line. It can have any of the following values:
sio_$stop_1, sio_$stop_1_point_5, or sio_$stop_2. The default
is sio_$stop_1.
sio_$susp_enable
This option is a Boolean value that enables or disables suspend
signals from the calling process. If true, the SIO line honors
suspend signals (faults). If false, the SIO line ignores
suspend signals (faults).
sio_$suspchr
The value of this option is the suspend character. It takes a
character value, and the default is CTRL/P.
sio_$value_t
A variant record type for passing the values of SIO options. The
diagram below illustrates the sio_$value_t data type:
15 8 7 0
______________________________________________________________
| Not Used | c |
______________________________________________________________
15 8 7 0
OR
15 0
______________________________________________________________
| i |
______________________________________________________________
15 0
OR
15 8 7 0
______________________________________________________________
| Not Used | b |
______________________________________________________________
15 8 7 0
OR
15 8 7 0
______________________________________________________________
| Not Used | es |
______________________________________________________________
15 8 7 0
c A character value.
i A 2-byte integer value.
b A Boolean value.
es A set of type sio_$err_enables_t.
Errors
sio_$bad_option
The option passed is not a valid SIO option.
sio_$illegal_strid
The stream ID passed in the sio_$ call is not open on an SIO line.
sio_$incompatible_speed
Attempted to set the speed for a partnered line that is incompatible
with the speed of the line's partner.