modem(7)modem(7)NAMEmodem - asynchronous serial modem line control
SYNOPSISDESCRIPTION
This section describes the two modes of modem line control and the
three types of terminal port access. It also discusses the effect of
the bits of the termio structure that affect modem line control. The
modem-related system calls (see ioctl(2)) are discussed at the end of
the manpage.
Definitions
There are several terms that are used within the following discussion
which will be defined here for reference.
"Modem control lines" (CONTROL) are generally defined as those outgoing
modem lines that are automatically controlled by the driver.
"Modem status lines" (STATUS) are generally defined as those incoming
modem lines that are automatically monitored by the driver.
CONTROL and STATUS for a terminal file vary according to the modem line
control mode of the file (see the section below).
An (see open(2)) to a port is considered to be BLOCKED if it is waiting
for another file on the same port to be closed.
An to a port is considered to be PENDING if it is waiting for the STA‐
TUS to be raised.
An to a port is considered to be SUCCESSFUL if the system call has
returned to the calling process without error.
Open Flag Bits
Currently, the only flag bits recognized by the driver are the and
bits. When either of these bits is set, an call to the driver will
never become blocked. If possible, the will be returned immediately as
SUCCESSFUL, and the driver will continue the process of opening the tty
file. If it is not possible, then the will be returned immediately
with the appropriate error code as described in the appropriate sec‐
tion.
Termio Bits
When set, the bit in the termios or termio structure (see termio(7)) is
used to remove the driver's automatic monitoring of the modem lines.
However, the user's ability to control the modem lines is determined
only by the mode in effect and does not depend on the state of Nor‐
mally, the driver will monitor and require the STATUS to be raised. An
system call will raise the CONTROL and wait for the STATUS before com‐
pleting unless the bit is set. (If the or bit is set, the will be
returned immediately, but the driver will otherwise continue to monitor
the modem lines as normal based on the state of the bit.) Normally,
loss of the STATUS will cause the driver to break the modem connection
and lower the CONTROL. However, if is set, any changes in the STATUS
will be ignored. A connection is required before any data may be read
or written, unless is set. Any timers that would normally be in effect
(see the and sections below) will be stopped while is set.
When the bit is changed from clear to set, the driver will assume the
existence of an active device (such as a modem) on the port regardless
of the STATUS. If any of the CONTROL are raised at that point in time,
they will continue in that state. The STATUS will no longer be
actively monitored. When the bit is changed from set to clear, the
driver will resume actively monitoring the STATUS. If all of the CON‐
TROL and STATUS are raised at that point in time, the driver will con‐
tinue the modem connection. If any of the STATUS are not raised, the
driver will act as though those signals were lost (as described in the
section below) and, if the device is a controlling terminal, a hangup
signal will be sent to the controlling process. If any of the CONTROL
are not raised, the driver will break the modem connection by lowering
all the CONTROL.
The bit in the termios or termio structure determines the action of the
driver regarding the CONTROL when the last system call (see close(2))
is issued to a terminal file. If the HUPCL bit is set, the driver will
lower the CONTROL at time and the modem connection will be broken. If
is not set and a modem connection exists, it will continue to exist,
even after the is issued. The driver will not change the CONTROL.
Terminal Port Access Types
There are three types of modem access: call-in connections, call-out
connections, and direct (no modem control) connections. A given port
may be accessed through all three types of connection by accessing dif‐
ferent files. The modem access type of a terminal file is determined
by the file's major and/or minor device numbers.
The call-in type of access is used when the connection is expected to
be established by an incoming call. This is the type that would be
used by getty(1M) to accept logins over a modem. When an is issued to
such a file, the driver may wait for an incoming call and will then
raise the CONTROL based on the current mode (see below) of the port.
When the port is closed, the driver may or may not lower the CONTROL
depending on the bit.
The call-out type of access is used when the connection is expected to
be established by an outgoing call. This would be used by programs
such as uucp(1). When an is issued to such a file, the driver will
immediately raise the CONTROL and wait for a connection based on the
mode currently in effect. When the port is closed, the driver may or
may not lower the CONTROL depending on the bit.
The direct type of access is used when no driver modem control is
desired. This could then be used for directly connected terminals that
use a three-wire connection, or to talk to a modem before a connection
has been established. The second case allows a program to give dialing
instructions to the modem. Neither the nor the bits have any effect on
a port accessed through a direct file. (However, both bits may be
inherited by other types of files; see the section below.) An to a
direct file does not affect the CONTROL and does not depend on any par‐
ticular state of the STATUS to succeed. When the file is closed, the
driver will not affect the state of the CONTROL. If a modem connection
has been established, it will continue to exist. Setting the speed of
a direct file to B0 (see termio(7) ) will be considered an impossible
speed change and will be ignored. It will not affect the CONTROL.
Modem Line Control Modes
There are two modes of modem line control: CCITT mode and simple mode.
A given port may have only one of these two modes in effect at any
given point in time. An attempt to open a port with a mode other than
the one in effect (from a PENDING or SUCCESSFUL on a different file)
will cause the to be returned with an error. The modem access type of
a terminal file is determined by the file's major and/or minor device
numbers.
CCITT mode is used for connections to switched line modems. The CON‐
TROL for CCITT mode are Data Terminal Ready (DTR) and Request to Send
(RTS). The STATUS are Data Set Ready (DSR), Data Carrier Detect (DCD),
and Clear to Send (CTS). Additionally, the Ring Indicator (RI) signal
indicates the presence of an incoming call. When a connection is begun
(an incoming call for a call-in file or an issued to a call-out file),
the CONTROL are raised and a connection timer (see the section below)
is started. If the STATUS become raised before the time period has
elapsed, a connection is established and the request is returned suc‐
cessfully. If the time period expires, the CONTROL are lowered and the
connection is aborted. For a call-in file, the driver will wait for
another incoming call; for a call-out file, the will be returned with
an error. Once a connection is established, loss of either DSR or CTS
will cause the CONTROL to be lowered and, if the device is a control‐
ling terminal, a hangup signal will be sent to the controlling process.
If DCD is lost, a timer is started. If DCD resumes before the time
period has expired, the connection will be maintained. However, no
data transfer will occur during this time. The driver will stop trans‐
mitting characters, and any characters received by the driver will be
discarded. (However, on some implementations data transmission cannot
be stopped. See the section.) If DCD is not restored within the
allotted time, the connection will be broken as described above for DSR
and CTS.
If the modem connection is to be broken when the system call is issued
(i.e. is set), then the CONTROL will be lowered and the will be
returned as successful. However, no further will be allowed until
after both DSR and CTS have been lowered by the modem, and the hangup
timer (see the section below) has expired. The action taken in
response to an during this time will be the same as if the port were
still open. (See the section below.)
When a port is in CCITT mode, the driver has complete control of the
modem lines and the user is not allowed to change the setting of the
CONTROL or affect which STATUS are actively monitored by the driver
(see the section below). This is to provide strict adherence with the
CCITT recommendations.
Simple mode is used for connections to devices which require only a
simple method of modem line control. This can include devices such as
black boxes, data switches, or for system-to-system connections. It
can also be used with modems which cannot operate under the CCITT rec‐
ommendations. The CONTROL for simple mode consists of only DTR. The
STATUS consists of only DCD. When an is issued, the CONTROL is raised
but no connection timer is started. When the STATUS becomes raised, a
connection is established and the request is returned as SUCCESSFUL.
Once a connection is established, loss of the STATUS will cause the
CONTROL to be lowered and, if the device is a controlling terminal, a
hangup signal will be sent to the controlling process.
When a port is in simple mode, the driver will normally control the
modem lines. However, the user is allowed to change the setting of the
CONTROL (see the section below).
Terminal Port Access Interlock
An interlock mechanism is provided between the three access types of
terminal files. It prevents more than one file from being successfully
opened at a time, but allows certain to succeed while others are PEND‐
ING so that a port can be opened through a call-out connection while
getty has a pending at a call-in connection. The three access types
are given a priority that determines which will succeed if more than
one file has an issued against it. The three access types are ordered
from lowest priority to highest as follows: call-in, call-out, and
direct.
If an is issued to a port which already has a SUCCESSFUL on it of a
lower priority type, the new will be returned with an error. (will
also be returned by an attempted on a CCITT call-out file if an incom‐
ing call indication is currently being received. In this case, if
there is a PENDING on the corresponding CCITT call-in file, this PEND‐
ING will complete.) If the lower priority is PENDING, the new will
succeed if possible, or will be left PENDING if waiting for the STATUS
and the lower priority will become BLOCKED. If a higher priority has
succeeded or is PENDING, the new will be BLOCKED, unless the new has
the flag bit set, in which case the will be returned with an error.
Once an on one type of file is SUCCESSFUL, any PENDING opens on lower
priority files will become BLOCKED.
When a file of one priority is closed, a BLOCKED on the next lower pri‐
ority type file will become active. If all of the STATUS are raised,
the will be SUCCESSFUL, otherwise the will become PENDING waiting for
the STATUS. If the lower priority is SUCCESSFUL (because the connec‐
tion was maintained when the higher priority file was closed), the port
characteristics (speed, parity, etc.) that were set by the higher pri‐
ority file will be inherited by the lower priority file. If the con‐
nection is not maintained through the the port characteristics will be
set to default values.
Modem Timers
There are four timers currently defined for use with modem connections.
The first three of the timers are applicable only to CCITT mode connec‐
tions. In general, the effect of changing a timer value while the
timer is running is system dependent. However, setting the timer value
to zero is guaranteed to disable the timer even if it is running.
The connect timer is used to limit the amount of time to wait for a
connection to be established once it has been begun. This timer is
started when an incoming call has been received on a call-in file, or
when an has been issued on a call-out file for which no opens are
already pending. If the connection is completed in time, the timer is
aborted. If the time period expires, the connection is aborted. For a
call-in file, the driver will again wait for an incoming call and the
will remain pending. For a call-out file, the will be returned with an
error.
The carrier detect timer is used to limit the amount of time to wait
before causing a disconnect if DCD drops. If carrier is not re-estab‐
lished in this time, a disconnect will occur. If carrier is re-estab‐
lished before the timeout, the timer will be aborted and the connection
maintained. During the period when carrier is not raised, no data will
be transferred across the line.
The no activity timer is used to limit the amount of time a connection
will remain open with no data transfer across the line. When the data
line becomes quiescent with no data transfer, this timer will be
started. If data is again transferred over the line in either direc‐
tion before the time limit, the timer will be aborted. If no activity
occurs before the timeout has occurred, the driver will disconnect the
line. This can be used to avoid long and costly telephone connections
when data transfer has been stopped either normally or abnormally.
The last timer defined, the hangup timer, is used for both CCITT and
simple modes. This timer controls the amount of time to wait after
disconnecting a modem line before allowing another This time period
should be made long enough to guarantee that the connection has been
terminated by the telephone switching equipment. If this period is not
long enough, the telephone connection may not be broken and a succeed‐
ing may complete with the old connection.
HP-UX Modem Ioctls
Several system calls apply to manipulation of modem lines. They use
the following information defined in
#define NMTIMER 6
typedef unsigned long mflag;
struct mtimer {
unsigned short m_timers[NMTIMER];
};
Each bit of the mflag long corresponds to one of the modem lines as
follows:
MRTS Request to Send outbound
MCTS Clear to Send inbound
MDSR Data Set Ready inbound
MDCD Data Carrier Detect inbound
MDTR Data Terminal Ready outbound
MRI Ring Indicator inbound
MDRS Data Rate Select outbound
The timer values are defined in the array The relative position of the
timer and default initial values and units for each timer are as fol‐
lows:
0 MTCONNECT 25 s
1 MTCARRIER 400 ms
2 MTNOACTIVITY 0 min
3 MTHANGUP 250 ms
4 Reserved
5 Reserved
A value of zero for any timer will disable that timer.
The modem line system calls have the form:
The commands using this form are:
Get the current state of both inbound and outbound modem lines and
store
in the long referenced by A raised line will be indi‐
cated by a one bit in the appropriate position.
Set the outbound modem lines from
the mflag long referenced by Setting an outbound bit to
one causes that line to be raised and zero to be low‐
ered. Setting bits for inbound lines has no effect.
Setting any bits while in CCITT mode has no effect. The
change to the modem lines is immediate and using this
form while characters are still being output may cause
unpredictable results.
Wait for the output to drain and set the new parameters as described
above.
Wait for the output to drain, then flush the input queue and set
the new parameters as described above.
The timer value system calls have the form:
The commands using this form are:
Get the current timer value settings and store in the
mtimer structure referenced by
Set the timer values from the structure referenced by
For any timer, setting the timer value to its previous value has no
effect.
SVID3 Modem Ioctls
System V Interface Definition, Third Edition (SVID3) specifies addi‐
tional system calls to manipulate the modem lines. They use informa‐
tion defined in
Each passes an integer argument in which each of the following bit def‐
initions correspond to one of the modem lines as follows:
TIOCM_RTS Request to Send outbound
TIOCM_CTS Clear to Send inbound
TIOCM_DSR Data Set Ready inbound
TIOCM_CAR Data Carrier Detect inbound
TIOCM_DTR Data Terminal Ready outbound
TIOCM_RNG Ring Indicator inbound
Additionally, is equivalent to and is equivalent to
The modem line system calls have the form:
The commands using this form are:
Get the current state of both inbound and outbound modem lines and
store
in the int referenced by A raised line will be indicated
by a one bit in the appropriate position.
Set the outbound modem lines from
the int referenced by
Raise the control lines specified by a one in the corresponding
bit positions of the int referenced by
Lower the control lines specified by a one in the corresponding
bit positions of the int referenced by
Note that setting bits for inbound lines has no effect, and setting any
bits while in CCITT mode has no effect. Also, the change to the modem
lines is immediate and using these ioctl's while characters are still
being output may cause unpredictable results.
WARNINGS
Occasionally it is possible that a process may open a call-out file at
approximately the same time as an incoming call is received. In some
cases, the call-out connection may be satisfied by the incoming call.
In general, however, the results are indeterminate. If necessary, the
situation can be avoided by the use of two modems and ports, one for
call-out connections and the other for receiving incoming calls.
DEPENDENCIES
Some hardware implementations may not have access to all modem lines
supported by MCSETA. If a particular hardware does not support a given
line, attempts to set the value of a line will be ignored, and reading
the current state of the line will return zero. The appropriate I/O
card manual should be referenced to determine the lines supported by
the hardware installed.
Some hardware implementations may not have access to all timers sup‐
ported by MCSETT. Also, the granularity of the individual timers may
vary depending on the hardware and system in use. The effect of set‐
ting a timer out of range or with a granularity outside the capability
of a particular system should be documented by that system. The effect
of changing the value for a timer while that timer is running is system
dependent and should be documented by each system.
Setting the bit while a timer is running will cause the timer to be
stopped. It is a system dependency whether or not the timer is
restarted, and if so, the value at which it is restarted when the bit
is subsequently cleared.
On those implementations supporting the HP27140A 6-Channel Multiplexer,
transmission of characters cannot be stopped during loss of DCD. The
driver cannot detect loss of DCD until the connection is broken. Also,
the I/O card may still have characters in its internal buffers and will
still try to transmit them.
AUTHOR
was developed by HP and AT&T.
FILESSEE ALSOstty(1), mknod(1M), ioctl(2), open(2), termio(7).
modem(7)