dial(3) CLIX dial(3)
NAME
dial - Establishes an outgoing terminal line connection
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <dial.h>
int dial(
CALL call );
void undial(
int fd );
PARAMETERS
call A CALL structure
fd A semaphore
DESCRIPTION
The dial() function 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 outgoing line */
char *telno; /* pointer to tel-no digits string */
int modem; /* modem control for direct lines */
char *device; /* unused */
int dev_len; /* unused */
} CALL;
The CALL element speed is 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 will
2/94 - Intergraph Corporation 1
dial(3) CLIX dial(3)
transmit 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. The CALL element baud is for the desired transmission
baud rate. For example, one might set baud to 110 and speed to 300 (or
1200). However, if speed is set to 1200, baud must be set to high (1200).
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 should be set to -1. This
will cause dial() to determine the correct value from the Devices file.
The telno element is for a pointer to a character string representing the
telephone number to be dialed. Such numbers may consist only of these
characters:
0-9 dial 0-9
* dial *
# dial #
= wait for secondary dial tone
- delay for approximately 4 seconds
The CALL element modem is used to specify modem control for direct lines.
This element should be nonzero if modem control is required. The CALL
element attr is a pointer to a termio structure, as defined in the
termio.h header file. A NULL value for this pointer element may be passed
to the dial() function, but if such a structure is included, the elements
specified in it will be set for the outgoing terminal line before the
connection is established. This is often important for certain attributes
such as parity and baud-rate.
The CALL elements device and dev_len are no longer used. They are
retained in the CALL structure for compatibility reasons.
An alarm() function 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 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() function, causing an apparent error return. If the user program
is to exist for an hour or more, error returns from read() should be
checked for (errno==EINTR), and the read() possibly reissued.
FILES
/usr/lib/uucp/Devices
2 Intergraph Corporation - 2/94
dial(3) CLIX dial(3)
/usr/lib/uucp/Systems
/usr/spool/uucp/LCK..tty-device
CAUTIONS
Including the dial.h header file automatically includes the termio.h
header file.
The above function uses stdio.h, which causes it to increase the size of
programs, not otherwise using standard I/O, more than might be expected.
RETURN VALUES
On failure, a negative value indicating the reason for the failure will be
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 /* acu problem (open() failure) */
L_PROB -6 /* line problem (open() failure) */
NO_Ldv -7 /* can't open Devices 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 */
DV_NT_E -12 /* requested speed does not match */
BAD_SYS -13 /* system not in Systems file*/
RELATED INFORMATION
Functions: alarm(2), read(2), write(2)
Files: acu(7), termio(7)
Commands: uucp(1)
2/94 - Intergraph Corporation 3