IOCOMM - Iocommd v.104

IOCOMM User and
Administration Guide

iocommd Overview

iocommd is a Unix tty port redirector. It is suitable for legacy applications (that open tty devices) and can also be used for printing, although LPD is normally a much better solution.

The procedure for configuring iocommd printing on the IOCOMM is given in Configuration.

This section provides information on setting up and using iocommd on host machines.

The IOCOMM peripheral daemon (iocommd) provides a client process with a full-duplex and transparent interface to a server port of its choice, via a pseudo-tty device. This presents a tty-like interface to the application in much the same way as a serial port.

The iocommd daemon is primarily intended as an interface between the client process and a printer, modem or data acquisition device. In the case of printers, it is recommended that the LPD protocol is used where possible.

By default, the daemon will fork into two processes during the start of a data transfer. The parent process will transfer data from the client to the server while the child process will transfer data from the server to the client. The parent also handles all the control aspects of the client-server link. The child process is normally terminated when the client process closes the slave pseudo-tty unless the -p option is used. In this case, the child is created at startup time and remains.

If the daemon is started without any arguments it will try and open the configuration file /etc/iocommd.conf which contains instructions on which daemons to start, for which peripherals, plus any optional arguments. Alternatively, a single daemon can be started from the shell with various arguments specified.

There are three mandatory arguments the daemon requires to mediate between the client and server port:

Server:

The host name of IOCOMM that has the attached printer or terminal.

Port:

The TCP port on which the IOCOMM port is listening for connection requests.

Link:

A mnemonic filename in /dev which shall be linked to the slave pseudo-tty selected by the daemon. This should be used as the interface device for client processes since the pseudo-tty may change during the daemon lifetime.

The other optional arguments modify the behaviour of the daemon in the way it controls connections and processes data to and from the peripheral. They are defined as follows:

Note: It should be noted, that iocommd does not support the -t (and consequently -s) switches. It supports raw data transfer mode only.

-p

The daemon maintains a continuous TCP connection to the access server port. This is useful for applications that require exclusive and uninterrupted access to a device. Note that no other daemon will be able to access such a port if any daemon is running to that port with this option.

-h

Hangs up the pseudo-tty if the TCP connection is lost. This mimics the situation in which a real serial port loses a signal such as DCD. In the same manner as the serial port, a SIGHUP signal will be sent to all processes that have the slave pseudo-tty as their controlling tty. See also -w.

-n

Converts all carriage returns read from the client process to carriage return and line feed. This is useful if using iocommd for printing and the print job is off the right margin (i.e. stair stepping).

-m

Push the STREAMS tty modules onto the slave pseudo-tty. This is useful for applications that expect to modify tty parameters as if a hardware device was attached. The modules pushed are the line discipline (normally called /dterm) and the hardware emulation (if supported). This option requires that the pseudo-tty architecture is based on the STREAMS I/O mechanism. The recommended Unix variants for using this option are those based on System V Release 3.Variants based on System V Release 4 should first try the -a option. Variants such as HP-UX, AIX, Xenix and SunOS do not require either option.

-a

Use the autopush facility to push STREAMS modules onto the slave pseudo-tty. This facility is supported on Unix System V Release 4 variants.

-u

Discard all data received from the peripheral. This is useful in cases where the peripheral is sending unwanted data to the host, which is not being read by the client and therefore may cause blockage problems on the pseudo-tty.

-w

Used with the -h and -p options. By default, on a hang-up, the daemon will open a new pseudo-tty before it has reconnected to the access server port. This option does the opposite and tries to re-establish the TCP connection first.

-o

Used with the -p option. This option prevents the slave pseudo-tty from closing so as to prevent any flushing of data that may occur. With this option set, the daemon will not close the TCP connection so its use is not advised for modems, as line hang-ups may not be initiated. It is useful for slow printers that may lose data on pseudo-tty close.

-f<file>

Specify a different configuration file. If the pathname is relative, the current working directory will be used.

-k<n>

This option checks if the TCP connection is still alive every n seconds. If the test fails, the child daemon process dies and signals the parent daemon that the connection is lost.

-x<n>

Set the daemon debug/diagnostic level to n. On startup, a log file called /var/iocommd.log is created (if not already there). All daemons on the host will write their debug and diagnostic messages to this file with a timestamp, daemon process ID and arguments attached to the actual diagnostic. The debug and diagnostics levels are:

0
Lets the world know we're alive, but nothing else.

1
Reports startup options.

2
Reports connection and disconnection events.

4
Reports numbers of characters being sent / received.

8
Displays data written to the client process.

16
Displays data written to IOCOMM.

32
Reports telnet negotiations.

64
Displays data read from IOCOMM.

128
Displays data read from the client process.

Adding the desired level numbers together can combine these levels. Care should be taken when a high debug level is set, because the log file could grow too large.

-c<n>

Network connection timeout option. The daemon will try for n seconds to establish a TCP connection, after which time, it will abort and discard any pending data. The default is to try forever.
An example of daemon configuration file is given below:

-x3 IOCOMM1 10011 IOCOMM1.11 -x35 -a -h xxx -c60 IOCOMM1 10013 IOCOMM1.13 -x39 -p -h -a -k60 IOCOMM2 10009 IOCOMM2.9

Each line represents a daemon to be started with the argument on that line.
The first line is a simple printer configuration. The second line is a complex modem configuration. The third line shows a configuration more suited to a daemon with a terminal attached and a getty running as the client process. Normally, the debug level is set to a minimal level such as 3.

Unix notes:
On some System V Release 4 variants, if the daemon writes to a non-existent client, the pseudo-tty may irretrievably hang up. In general, make sure there is always a client process running if there is the possibility of data being received for it.

On SunOS, if a getty is the client process running to a terminal then the login prompt may be corrupted on the screen, but this goes when the user name is typed in. The UUCP command uucico may not work with iocommd on Solaris 2.1 (Intel).

Some systems may not properly propogate the SIGHUP signal associated with the -h option.

000127

Links to Other Chapters

Server:	The host name of IOCOMM that has the attached printer or terminal.
Port:	The TCP port on which the IOCOMM port is listening for connection requests.
Link:	A mnemonic filename in `/dev` which shall be linked to the slave pseudo-tty selected by the daemon. This should be used as the interface device for client processes since the pseudo-tty may change during the daemon lifetime.

`-p`	The daemon maintains a continuous TCP connection to the access server port. This is useful for applications that require exclusive and uninterrupted access to a device. Note that no other daemon will be able to access such a port if any daemon is running to that port with this option.
`-h`	Hangs up the pseudo-tty if the TCP connection is lost. This mimics the situation in which a real serial port loses a signal such as DCD. In the same manner as the serial port, a SIGHUP signal will be sent to all processes that have the slave pseudo-tty as their controlling tty. See also `-w`.
`-n`	Converts all carriage returns read from the client process to carriage return and line feed. This is useful if using iocommd for printing and the print job is off the right margin (i.e. stair stepping).
`-m`	Push the STREAMS tty modules onto the slave pseudo-tty. This is useful for applications that expect to modify tty parameters as if a hardware device was attached. The modules pushed are the line discipline (normally called `/dterm`) and the hardware emulation (if supported). This option requires that the pseudo-tty architecture is based on the STREAMS I/O mechanism. The recommended Unix variants for using this option are those based on System V Release 3.Variants based on System V Release 4 should first try the `-a` option. Variants such as HP-UX, AIX, Xenix and SunOS do not require either option.
`-a`	Use the autopush facility to push STREAMS modules onto the slave pseudo-tty. This facility is supported on Unix System V Release 4 variants.
`-u`	Discard all data received from the peripheral. This is useful in cases where the peripheral is sending unwanted data to the host, which is not being read by the client and therefore may cause blockage problems on the pseudo-tty.
`-w`	Used with the `-h` and `-p` options. By default, on a hang-up, the daemon will open a new pseudo-tty before it has reconnected to the access server port. This option does the opposite and tries to re-establish the TCP connection first.
`-o`	Used with the `-p` option. This option prevents the slave pseudo-tty from closing so as to prevent any flushing of data that may occur. With this option set, the daemon will not close the TCP connection so its use is not advised for modems, as line hang-ups may not be initiated. It is useful for slow printers that may lose data on pseudo-tty close.
`-f<file>`	Specify a different configuration file. If the pathname is relative, the current working directory will be used.
`-k<n>`	This option checks if the TCP connection is still alive every `n` seconds. If the test fails, the child daemon process dies and signals the parent daemon that the connection is lost.

`-x<n>`	Set the daemon debug/diagnostic level to `n`. On startup, a log file called `/var/iocommd.log` is created (if not already there). All daemons on the host will write their debug and diagnostic messages to this file with a timestamp, daemon process ID and arguments attached to the actual diagnostic. The debug and diagnostics levels are:
	`0`	Lets the world know we're alive, but nothing else.
	`1`	Reports startup options.
	`2`	Reports connection and disconnection events.
	`4`	Reports numbers of characters being sent / received.
	`8`	Displays data written to the client process.
	`16`	Displays data written to IOCOMM.
	`32`	Reports telnet negotiations.
	`64`	Displays data read from IOCOMM.
	`128`	Displays data read from the client process.
	Adding the desired level numbers together can combine these levels. Care should be taken when a high debug level is set, because the log file could grow too large.

`-c<n>`	Network connection timeout option. The daemon will try for `n` seconds to establish a TCP connection, after which time, it will abort and discard any pending data. The default is to try forever. An example of daemon configuration file is given below:
	`-x3 IOCOMM1 10011 IOCOMM1.11 -x35 -a -h xxx -c60 IOCOMM1 10013 IOCOMM1.13 -x39 -p -h -a -k60 IOCOMM2 10009 IOCOMM2.9`
	Each line represents a daemon to be started with the argument on that line. The first line is a simple printer configuration. The second line is a complex modem configuration. The third line shows a configuration more suited to a daemon with a terminal attached and a getty running as the client process. Normally, the debug level is set to a minimal level such as 3.