hpux modem man page on unix.com

modem(7) Miscellaneous Information Manual modem(7)

NAME
modem - asynchronous serial modem line control

SYNOPSIS
DESCRIPTION
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 STATUS 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
section.

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
Normally, the driver will monitor and require the STATUS to be raised. An system call will raise the CONTROL and wait for the STATUS
before completing 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 regard-
less 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
CONTROL and STATUS are raised at that point in time, the driver will continue 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 different 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 particular 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 CONTROL 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 successfully. If the time period expires, the CONTROL are low-
ered 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 controlling 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 transmitting 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 SUC-
CESSFUL. 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 success-
fully opened at a time, but allows certain to succeed while others are PENDING 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 incoming call indication is currently being received. In this case, if
there is a PENDING on the corresponding CCITT call-in file, this PENDING 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 priority 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
priority file will be inherited by the lower priority file. If the connection 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
connections. 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-established before the timeout, the timer will be aborted and the connec-
tion 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 abnor-
mally.

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 suc-
ceeding 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
follows:

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 indicated 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 lowered. 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 additional system calls to manipulate the modem lines. They use information
defined in

Each passes an integer argument in which each of the following bit definitions 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 neces-
sary, 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 appropri-
ate 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 supported by MCSETT. Also, the granularity of the individual timers may
vary depending on the hardware and system in use. The effect of setting 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.

FILES
SEE ALSO
stty(1), mknod(1M), ioctl(2), open(2), termio(7).

modem(7)

hpux man page for modem