modem(7) modem(7)
NAME [Toc] [Back]
modem - asynchronous serial modem line control
SYNOPSIS [Toc] [Back]
#include <sys/modem.h>
DESCRIPTION [Toc] [Back]
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 ioctl(2) system calls are discussed at the end of the
document.
Definitions [Toc] [Back]
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 Modem line control modes below). An open(2) to a port will
be considered to be BLOCKED if it is waiting for another file on the
same port to be closed. An open to a port is considered to be PENDING
if it is waiting for the STATUS to be raised. An open to a port is
considered to be SUCCESSFUL if the open system call has returned to
the calling process without error.
Open flag bits [Toc] [Back]
Currently, the only open flag bits recognized by the driver is the
O_NDELAY and O_NONBLOCK bits. When either of these bits is set, an
open call to the driver will never become blocked. If possible, the
open 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 open will be returned immediately with the appropriate error
code as described in the appropriate section.
Termio bits [Toc] [Back]
When set, the CLOCAL 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 CLOCAL. Normally, the driver will monitor and require the
STATUS to be raised. An open system call will raise the CONTROL and
wait for the STATUS before completing unless the CLOCAL bit is set.
(If the O_NDELAY or O_NONBLOCK bit is set, the open will be returned
immediately, but the driver will otherwise continue to monitor the
modem lines as normal based on the state of the CLOCAL bit.) Normally,
loss of the STATUS will cause the driver to break the modem connection
and lower the CONTROL. However, if CLOCAL is set, any changes in the
STATUS will be ignored. A connection is required before any data may
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
modem(7) modem(7)
be read or written, unless CLOCAL is set. Any timers that would
normally be in effect (see Modem line control modes and Modem timers
below) will be stopped while CLOCAL is set.
When the CLOCAL 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 CLOCAL 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 Modem line control modes 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 HUPCL bit in the termios or termio structure determines the action
of the driver regarding the CONTROL when the last close system call is
issued to a terminal file. If the HUPCL bit is set, the driver will
lower the CONTROL at close time and the modem connection will be
broken. If HUPCL is not set and a modem connection exists, it will
continue to exist, even after the close is issued. The driver will
not change the CONTROL.
Terminal port access types [Toc] [Back]
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 open 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 HUPCL 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 open 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 HUPCL 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
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
modem(7) modem(7)
connection has been established. The second case allows a program to
give dialing instructions to the modem. Neither the CLOCAL nor the
HUPCL bits have any effect on a port accessed through a direct file.
(However, both bits may be inherited by other types of files; see
Terminal port access interlock below.) An open 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 [Toc] [Back]
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 open on a different
file) will cause the open to be returned with an [ENXIO] 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 open issued to a
call-out file), the CONTROL are raised and a connection timer (see
Modem timers below) is started. If the STATUS become raised before
the time period has elapsed, a connection is established and the open
request is returned successfully. 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 open will be returned with an [EIO] 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 DEPENDENCIES.) 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 close system call is
issued (i.e. HUPCL is set), then the CONTROL will be lowered and the
close will be returned as successful. However, no further opens will
be allowed until after both DSR and CTS have been lowered by the
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
modem(7) modem(7)
modem, and the hangup timer (see Modem timers below) has expired. The
action taken in response to an open during this time will be the same
as if the port were still open. (See Terminal port access interlock
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 Modem ioctls 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
recommendations. The CONTROL for simple mode consists of only DTR.
The STATUS consists of only DCD. When an open is issued, the CONTROL
is raised but no connection timer is started. When the STATUS becomes
raised, a connection is established and the open 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 Modem ioctls below).
Terminal port access interlock [Toc] [Back]
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 opens to succeed
while others are PENDING so that a port can be opened through a callout
connection while getty has a pending open at a call-in connection.
The three access types are given a priority that determines which open
will succeed if more than one file has an open issued against it. The
three access types are ordered from lowest priority to highest as
follows: call-in, call-out, and direct.
If an open is issued to a port which already has a SUCCESSFUL open on
it of a lower priority type, the new open will be returned with an
[EBUSY] error. ([EBUSY] will also be returned by an attempted open on
a CCITT call-out file if an incoming call indication is currently
being received. In this case, if there is a PENDING open on the
corresponding CCITT call-in file, this PENDING open will complete.) If
the lower priority open is PENDING, the new open will succeed if
possible, or will be left PENDING if waiting for the STATUS and the
lower priority open will become BLOCKED. If a higher priority open
has succeeded or is PENDING, the new open will be BLOCKED, unless the
new open has the O_NDELAY flag bit set, in which case the open will be
returned with an [EBUSY] error. Once an open on one type of file is
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
modem(7) modem(7)
SUCCESSFUL, any PENDING opens on lower priority files will become
BLOCKED.
When a file of one priority is closed, a BLOCKED open on the next
lower priority type file will become active. If all of the STATUS are
raised, the open will be SUCCESSFUL, otherwise the open will become
PENDING waiting for the STATUS. If the lower priority open is
SUCCESSFUL (because the connection 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 close, the port characteristics will be set to default values.
Modem timers [Toc] [Back]
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 open 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 open will remain pending. For a call-out file, the open will be
returned with an [EIO] 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 reestablished
in this time, a disconnect will occur. If carrier is reestablished
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
direction 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 open. This time
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
modem(7) modem(7)
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
succeeding open may complete with the old connection.
HP-UX Modem ioctls [Toc] [Back]
Several ioctl system calls apply to manipulation of modem lines. They
use the following information defined in <sys/modem.h>:
#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 m_timers. 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 ioctl system calls have the form:
int ioctl(int fildes, int command, mflag *arg);
The commands using this form are:
MCGETA Get the current state of both inbound and outbound
modem lines and store in the mflag long referenced by
arg. A raised line will be indicated by a one bit in
the appropriate position.
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
modem(7) modem(7)
MCSETA Set the outbound modem lines from the mflag long
referenced by arg. 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.
MCSETAW Wait for the output to drain and set the new parameters
as described above.
MCSETAF Wait for the output to drain, then flush the input
queue and set the new parameters as described above.
The timer value ioctl system calls have the form:
int ioctl(int fildes, int command, mtimer *arg);
The commands using this form are:
MCGETT Get the current timer value settings and store in the
mtimer structure referenced by arg.
MCSETT Set the timer values from the structure referenced by
arg.
For any timer, setting the timer value to its previous value has no
effect.
SVID3 Modem ioctls [Toc] [Back]
System V Interface Definition, Third Edition (SVID3) specifies
additional ioctl system calls to manipulate the modem lines. They use
information defined in <termios.h>.
Each ioctl 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, TIOCM_CD is equivalent to TIOCM_CAR, and TIOCM_RI is
equivalent to TIOCM_RNG.
The modem line ioctl system calls have the form:
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
modem(7) modem(7)
int ioctl(int fildes, int command, int *arg);
The commands using this form are:
TIOCMGET Get the current state of both inbound and outbound
modem lines and store in the int referenced by arg. A
raised line will be indicated by a one bit in the
appropriate position.
TIOCMSET Set the outbound modem lines from the int referenced by
arg.
TIOCMBIS Raise the control lines specified by a one in the
corresponding bit positions of the int referenced by
arg.
TIOCMBIC Lower the control lines specified by a one in the
corresponding bit positions of the int referenced by
arg.
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 [Toc] [Back]
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 [Toc] [Back]
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
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 CLOCAL bit while a timer is running will cause the timer
to be stopped. It is a system dependency whether or not the timer is
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
modem(7) modem(7)
restarted, and if so, the value at which it is restarted when the
CLOCAL 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 [Toc] [Back]
modem was developed by HP and AT&T.
FILES [Toc] [Back]
/dev/cua*
/dev/cul*
/dev/tty*
/dev/ttyd*
SEE ALSO [Toc] [Back]
stty(1), mknod(1M), ioctl(2), open(2), termio(7).
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003 [ Back ] |
