dial(3C)

NAME

dial(), undial() − establish an out-going terminal line connection

SYNOPSIS

#include <dial.h>

int dial(CALL call);

void undial(int fd);

DESCRIPTION

dial() returns a file-descriptor for a terminal line open for read/write. The argument to dial() is a CALL structure (defined in the <dial.h> header file).

When finished with the terminal line, the calling program must invoke undial() to release the semaphore that has been set during the allocation of the terminal device.

The definition of CALL in the <dial.h> header file is:

typedef struct {
    struct termio    *attr;    /* pointer to termio attribute struct */
    int              baud;     /* transmission data rate */
    int              speed;    /* 212A modem: low=300, high=1200 */
    char             *line;    /* device name for out-going line */
    char             *telno;   /* pointer to tel-no digits string */
    int              modem;    /* specify modem control for direct lines */
    char             *device; /* Will hold the name of the device used
                                  to make a connection */
    int              dev_len; /* The length of the device used to
                                  make connection */
} CALL;

CALL elements are as follows:

speed Intended only for use with an outgoing dialed call, in which case its value should be either 300 or 1200 to identify the 113A modem, or the high- or low-speed setting on the 212A modem. Note that the 113A modem or the low-speed setting of the 212A modem transmits at any rate between 0 and 300 bits per second. However, the high-speed setting of the 212A modem transmits and receives at 1200 bits per second only.

baud Desired transmission baud rate. For example, one might set baud to 110 and speed to 300 (or 1200). However, if speed set to 1200 baud must be set to high (1200).

line If the desired terminal line is a direct line, a string pointer to its device-name should be placed in the line element in the CALL structure. Legal values for such terminal device names are kept in the Devices file. In this case, the value of the baud element need not be specified as it will be determined from the Devices file.

telno A pointer to a character string representing the telephone number to be dialed. Such numbers can consist only of symbols described below. The termination symbol is supplied by the dial() function, and should not be included in the telno string passed to dial() in the CALL structure.

Permissible codes
0-9	dial 0-9
* or :	dial *
# or ;	dial #
-	4-second delay for second dial tone
e or <	end-of-number
w or =	wait for secondary dial tone
f	flash off hook for 1 second

modem Specifies modem control for direct lines. Set to non-zero if modem control is required.

attr Pointer to a termio structure, as defined in the <termio.h> header file. A NULL value for this pointer element can be passed to the dial() function, but if such a structure is included, the elements specified in it are set for the outgoing terminal line before the connection is established. This is often important for certain attributes such as parity and baud-rate.

device Holds the device name (cul..) that establishes the connection.

dev_len Length of the device name that is copied into the array device.

RETURN VALUE

On failure, a negative value indicating the reason for the failure is returned. Mnemonics for these negative indices as listed here are defined in the <dial.h> header file.

INTRPT    -1     /* interrupt occurred */
D_HUNG    -2     /* dialer hung (no return from write) */
NO_ANS    -3     /* no answer within 10 seconds */
ILL_BD    -4     /* illegal baud-rate */
A_PROB    -5     /* automatic call unit (acu) problem (open() failure) */
L_PROB    -6     /* line problem (open() failure) */
NO_Ldv    -7     /* can’t open LDEVS file */
DV_NT_A   -8     /* requested device not available */
DV_NT_K   -9     /* requested device not known */
NO_BD_A   -10    /* no device available at requested baud */
NO_BD_K   -11    /* no device known at requested baud */

WARNINGS

Including the <dial.h> header file automatically includes the <termio.h> header file.

The above routine uses <stdio.h>, which causes unexpected increases in the size of programs that otherwise do not use standard I/O.

DEPENDENCIES

HP Clustered Environment

dial() is not supported on client nodes of an HP Cluster.

Series 300/400

An alarm() (see alarm(2)) system call for 3600 seconds is made (and caught) within the dial() module for the purpose of “touching” the LCK.. file and constitutes the device allocation semaphore for the terminal device. Otherwise, uucp(1) may simply delete the LCK.. entry on its 90-minute clean-up rounds. The alarm may go off while the user program is in a read() or write() system call, causing an apparent error return. If the user program expects to be around for an hour or more, error returns from reads should be checked for (errno==EINTR), and the read possibly reissued.

FILES

/usr/lib/uucp/Devices
/usr/spool/uucp/LCK..tty-device

Museum

Related Articles