dial(3N) dial(3N)
NAME
dial - establish an outgoing terminal line connection
SYNOPSIS
cc [options] file -lnsl
#include <dial.h>
int dial(CALL call);
void undial(int fd);
DESCRIPTION
dial returns a file-descriptor for a terminal line open for
reading or writing. The argument to dial is a CALL structure.
The CALL structure is defined in the dial.h header file.
When it is finished with a terminal line, the calling program
should call undial to add HUPCL to the c_flags of the termios
structure for that line.
The definition of CALL in the dial.h header file is:
typedef struct {
struct termio *attr;/* pointer to termio attribute struct */
int baud; /* unused */
int speed; /* 212A modem: low=300, high=1200 */
char *line; /* device name for outgoing line */
char *telno; /* pointer to telno digits string */
int modem; /* specify modem control for direct lines */
char *device; /* pointer to CALL_EXT structure */
int dev_len; /* unused */
} CALL;
The elements of the CALL structure are defined below:
speed Intended only for use with an outgoing dialed call.
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 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.
baud This element is currently ignored.
Copyright 1994 Novell, Inc. Page 1
dial(3N) dial(3N)
line If the requested terminal line is a direct line, a
string pointer to its device name should be placed
in the line element of 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 value will
cause dial to determine the correct value from the
Devices file.
telno A pointer to a character string representing the
telephone number of a system name 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
modem Used to specify modem control for direct lines.
This element should be non-zero if modem control is
required.
attr 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 setting
is often important for certain attributes such as
parity and baud rate.
dev_len This CALL element is no longer used. It is retained
in the CALL structure for compatibility.
device This CALL extension is defined as:
typedef struct {
char *service; /* name of service to use (default = cu) */
char *class; /* class of device to use */
char *protocol; /* returns the protocol string for the
connection made */
char *reserved1; /* unused */
} CALL_EXT;
If the device element of the CALL structure is NULL,
that is, if it does not point to a CALL_EXT
structure, then service is assumed to be cu, class
Copyright 1994 Novell, Inc. Page 2
dial(3N) dial(3N)
is assumed to be NULL, and the protocol string is
not returned to the application. This preserves
both binary and source compatibility with existing
applications.
The service element of the CALL_EXT structure is
used by ct, cu, and uucico. If service is not
specified, it defaults to cu.
The class field supplies dial with the class
parameter for the dialup connection. The default
class is NULL. See the -c option of cu(1C) for the
meaning of class.
protocol points to an area of static storage that
contains the processed protocol field for the device
used for the connection. The protocol string is
reported back to the application via the Connection
Server interface. The default protocol string is
NULL.
Files
/etc/uucp/Devices
/etc/uucp/Systems
/var/spool/locks/LCK..tty-device
Return Values
On failure, a negative value indicating the reason for the
failure will be returned. Mnemonics for these negative
indexes as listed here are defined in the dial.h header file.
INTRPT -1 /* interrupt occurred */
D_HUNG -2 /* dialer failed */
NO_ANS -3 /* no answer (login or invoke scheme failed) */
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 */
CS_PROB -14/* could not connect to the connection
server */
DV_W_TM -15/* not allowed to call at this time */
Copyright 1994 Novell, Inc. Page 3
dial(3N) dial(3N)
REFERENCES
cs(1M), uucp(1C), alarm(2), read(2), write(2), cs_connect(3N),
termio(7)
NOTICES
Including the dial.h header file automatically includes the
termio.h header file.
An 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(1C) 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(2) or write(2)
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.
dial is an interface call to the Connection Server daemon.
The Connection Server establishes the connection and passes
back to dial the file descriptor. See cs(1M) and
cs_connect(3N) for more information.
The lock files that act as semaphores for devices
(var/spool/locks/LC...) are created and maintained by the
Connection Server. They don't have to (and shouldn't be)
removed by the user.
Copyright 1994 Novell, Inc. Page 4