modem(7)

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 Modem Line Control Modes section below).

An open() (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 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

Currently, the only open() flag bits recognized by the driver are 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

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 be read or written, unless CLOCAL is set. Any timers that would normally be in effect (see the Modem Line Control Modes and Modem Timers sections 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 the Modem Line Control Modes 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 HUPCL bit in the termios or termio structure determines the action of the driver regarding the CONTROL when the last close() system call (see close(2)) 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

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 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 the Terminal Port Access Interlock section 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

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 the Modem Timers section 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 the DEPENDENCIES 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 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 open()s will be allowed until after both DSR and CTS have been lowered by the modem, and the hangup timer (see the Modem Timers section 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 the Terminal Port Access Interlock 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 Modem Ioctls 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 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 the Modem Ioctls 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 open()s to succeed while others are PENDING so that a port can be opened through a call-out 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 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

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 re-established in this time, a disconnect will occur. If carrier is re-established 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 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

Several ioctl() system calls apply to manipulation of modem lines. They use the following information defined in <sys/modem.h>:

Each bit of the mflag long corresponds to one of the modem lines as follows:

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:

A value of zero for any timer will disable that timer.

The modem line ioctl() system calls have the form:

The commands using this form are:

The timer value ioctl() system calls have the form:

The commands using this form are:

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 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:

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:

The commands using this form are:

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.