NAME
ctb - MachTen Communications ToolBox Devices

DESCRIPTION
MachTen’s CommToolBox devices provide a Unix device interface to
the Connection Manager component of the Macintosh Communications
Toolbox. CommToolBox devices allow Unix programs to use any
Connection Manager Tool for standard input and output, just as if
they are using a typical tty device. However, the Connection
Manager Tools completely handle and hide the details of the
physical connections from the Unix programs, allowing the programs
to concentrate on the logical stream of data to and from the
device, and to be oblivious to the underlying hardware properties
like modem types, baud rates, flow control mechanisms, etc.

The default CommToolBox devices are /dev/cm.in and /dev/cm.out. The
.in and .out correspond to dial-in and dial-out (discussed below).
CommToolBox devices use the major number 11. The minor number 0
indicates a CommToolBox device that "listens" on the Connection
Tool for incoming connections. This is most useful for dial-in
modem lines. The minor number 128 indicates a CommToolBox device
that "opens" the Connection Tool. This will actively open the
Connection Tool and dial-out, if appropriate. Some Connection
Tools do not have the dual modes of dial-in and dial-out (e.g., the
Serial Tool). These tools usually require an "open" rather than a
"listen", and thus require use of the minor number 128.

USING THE COMMTOOLBOX DEVICES
CommToolBox devices are either "unconfigured devices" or
"configured devices". Both "/dev/cm.in" and "/dev/cm.out" are
unconfigured CommToolBox devices. An unconfigured device has no
stored information indicating which tool it connects to or the
specific attributes of any tool. An unconfigured device can thus
be used to open a connection to any Communications ToolBox
Connection Tool.

When an unconfigured device is opened by a Unix application, the
application is blocked until the device is configured. To enable
the user to configure the device, the Communication Manager
displays its configuration dialog box in front of any open MachTen
windows. This dialog box allows the user to select a particular
Connection Tool and to configure it. The Unix application is
unblocked when the configuration dialog box is closed, and proceeds
to "open" or "listen" on the Connection Tool, depending on the
minor number of the unconfigured device. If the user cancels the
configuration dialog, or the Connection Tool fails to open
properly, the device is closed and an error is returned to the Unix
application.

For each successfully configured "unconfigured device", a new item
is added to the end of MachTen’s File menu. These menu items may
be selected, which allows that particular configuration to be saved
in a file. Files created in this manner become "configured
CommToolBox devices".

Configured CommToolBox devices can be stored anywhere on the
Macintosh File System. The typical repository is /dev, which is
where all other devices reside. When a configured device is opened
by a Unix application, the saved configuration is used to create a
CommToolBox connection of the same type of Connection Tool as the
configuration that was previously saved. This connection is
immediatley "opened" or "listened" on, appropriately. An error is
returned if the Connection Tool specified by the configured device
cannot be found or configured. There is no new item added to the
end of MachTen’s File menu for successfully opened "configured
devices". The only way to change the settings for a configured
device is to open an "unconfigured device", configure it
appropriately, and save it as a "configured device". Configured
devices can be discarded when they are no longer needed by dragging
them to the Trash.

MachTen supports up to 3 simultaneously opened (or listening on)
CommToolBox devices. Attempts to open subsequent devices will
return an error.

CONFIGURING UNIX PROGRAMS
Unix serial communications programs like tip, pppd, and SLIP
usually require intimate knowledge of the physical connection
media. The attributes of each connection are often stored in a
collection of configuration files. The classifications of these
attributes are built into each program, and often lag behind the
rapidly-changing characteristics of today’s communication
mechanisms. Since other "logical" connection attributes are also
stored in these Unix configuration files, CommToolBox devices do
not completely remove the need for these databases. However,
MachTen’s CommToolBox devices allow most Unix communications
programs to be configured with only a minimal set of logical
attributes, and still work with a variety of physical connection
media. This simplification can greatly reduce the effort required
to configure and maintain communications with new advanced modems
or other physical connections.

EXAMPLES
Each of the following examples shows a minimal logical
configuration for the most common Unix serial communications
programs. These examples demonstrate the use of unconfigured
CommToolBox devices which enable the minimal configuration to be
used to open any Connection Tool. This way, the desired Connection
Tool itself can be used to select the specific attributes of the
physical connection. Once the Connection Tool is operating
properly, its configuration may be saved in a configured
CommToolBox device and this device can be used in place of the
unconfigured device shown in these examples.

Using PPP with CommToolBox Devices

Pppd does not use any device configuration database, but rather
takes all of its arguments on the command line. A minimal pppd
command line to passively listen for PPP connections on any
Connection Tool can be invoked as follows:

# /usr/etc/pppd /dev/cm.in 101.0.0.2: -p -d &

A minimal pppd command line to actively open a PPP connection on
any Connection Tool can be invoked as follows:

# /usr/etc/pppd /dev/cm.out 101.0.0.1: -d &

Using Tip with CommToolBox Devices

Tip is designed to timeout on hard-wired connections that do not
open in less than 10 seconds. Since Connection Tools abstract the
hardware details from the Unix programs, tip believes CommToolBox
devices are hard-wired. To prevent tip from timing out on
CommToolBox device opens, the attribute :ct#0: should be added to
the /etc/remote entry for the CommToolBox device. This attribute
has been added to the tip program specifically for use with the
MachTen CommToolBox devices. It is not described in the tip manual
page. The value 0 indicates no timeout is necessary. Any other
value indicates a timeout in seconds. The default used if no :ct:
attribute is specified is 10 seconds.

A minimal /etc/remote configuration to open a tip session on any
Connection Tool follows:

cm.out:dv=/dev/cm.out:ct#0

To open a tip session using this configuration, invoke the
following command:

# tip cm.out

Using Getty with CommToolBox Devices

This is an example of a minimal /etc/ttys entry to enable getty to
listen on any Connection Tool for incoming login sessions. The
9600 baud rate specified here will be ignored by the Connection
Tool. The baud rate specified in the Connection Manager’s
Configuration dialog box will be the actual baud rate used.

cm.in "/etc/getty std.9600" vt100 on
secure

Getty is automatically started by init and need not be invoked from
the command line. If you make a change to the /etc/ttys database,
you can inform init of this change using the following command:

# kill -HUP 1

Using SLIP with CommToolBox Devices

The easiest way to establish a SLIP connection is via the "-s"
option provided in tip. A minimal /etc/remote configuration to
open a SLIP connection on any Connection Tool follows:

joe.slip: :dv=/dev/cm.out:hc:ct#0: :sa=89.0.0.2:sm=225.0.0.0:da=89.0.0.1:st=slip: :ls=/etc/login.script.joe:

To establish a SLIP connection using this configuration, invoke the
following command:

# tip -s joe.slip

NOTES
Hardware Flow Control

It is necessary to have the proper cable for your type of modem and
the corresponding Connection Tool in order for hardware flow
control to function properly. There are several different modem
cables manufactured for the Macintosh, and they are definitely not
equal with respect to flow control signals. Apple has provided a
nice picture of the pinouts required by the Apple Modem Tool. The
picture is a PICT resource, ID 20000, contained in the Apple Modem
Tool extension. Use ResEdit to display or print this picture.

Hardware flow control and detection of dropped Carrier Detect (CD)
are still mutually exclusive under MachTen when using /dev/ttya and
/dev/ttyfa. If you require both hardware flow control and
detection of dropped CD, use the CommToolBox devices.

Dial-In Dial-Out

MachTen CommToolBox devices do not support simultaneous dial-in and
dial-out on the same Connection Tool. This capability may be added
to a subsequent release of MachTen.