'\"macro stdmacro
.if n .pH g3c.dial @(#)dial	40.12 of 12/12/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} dial 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} dial 3C "C Programming Language Utilities"
.if \nX=2 .ds x} dial 3C "" "\&"
.if \nX=3 .ds x} dial "" "" "\&"
.TH \*(x}
.SH NAME
\f4dial\f1 \- establish an outgoing terminal line connection
.SH SYNOPSIS
\f4\#include <dial.h>\f1
.PP
\f4int dial (CALL call);\f1
.PP
\f4void undial (int fd);\f1
.SH DESCRIPTION
\f4dial\fP returns a file-descriptor for a terminal line open for read/write.
The argument to \f4dial\fP is a \f4CALL\fP structure (defined in the
\f4dial.h\f1 header file).
.P
When finished with the terminal line, the calling program must 
invoke \f4undial\f1 to release the semaphore that has been set
during the allocation of the terminal device.
.PP
The definition of \f4CALL\fP in the \f4dial.h\f1 header file is:
.PP
.nf
.ta .5i 1.3i 2.0i 2.8i
\s-1\f4typedef 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;	/\(** unused \(**/
	int	dev_len;	/\(** unused \(**/
} CALL;\fP\s+1
.fi
.PP
The \f4CALL\fP element \f4speed\f1 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 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 \f4CALL\fP element \f4baud\f1 is for the desired transmission baud rate.
For example, one might set \f4baud\f1 to 110 and \f4speed\f1 to 300 (or 1200).
However, if \f4speed\f1 is set to 1200, \f4baud\f1 must be set to high (1200).
.P
If the desired terminal line is a direct line, a string
pointer to its device-name should be placed in the \f4line\fP
element in the \f4CALL\fP structure.
Legal values for such terminal device names are kept in the \f4Devices\f1 file.
In this case, the value of the \f4baud\f1
element should be set to -1.
This value will cause \f4dial\f1 to determine the correct value
from the \f4Devices\f1 file.
.P
The \f4telno\f1 element is for a pointer to a character string
representing the telephone number to be dialed.
Such numbers may consist only of these characters:
.sp .5
.nf
.in +2m
0-9	dial 0-9
\(**	dial \(**
#	dial #
=	wait for secondary dial tone
\-	delay for approximately 4 seconds
.in -2m
.fi
.sp .5
.P
The \f4CALL\fP element \f4modem\f1
is used to specify modem control for direct lines.
This element should be non-zero if modem control is required.
The \f4CALL\fP element \f4attr\f1 is a pointer to a \f4termio\fP
structure, as defined in the \f4termio.h\f1 header file.
A \f4NULL\fP value for this pointer element may be passed to the \f4dial\fP
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.
.PP
The \f4CALL\fP elements \f4device\f1 and \f4dev_len\f1 are no longer used.
They are retained in the \f4CALL\fP structure for compatibility reasons.
.SH FILES
\f4/etc/uucp/Devices\fP
.br
\f4/etc/uucp/Systems\fP
.br
\f4/var/spool/uucp/LCK..\f2tty-device\f1
.SH "SEE ALSO"
\f4alarm\fP(2), \f4read\fP(2), \f4write\fP(2).
.sp .2
\f4termio\fP(7) in the
.IR "System Administrator's Reference Manual".
.sp .2
\f4uucp\fP(1C) in the
\f2User's Reference Manual\f1.
.SH DIAGNOSTICS
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 \f4dial.h\fP
header file.
.nf
.ta .5i 1.3i 2.0i
	\s-1\f4INTRPT	\-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\(**/\fP\s+1
.fi
.SH NOTES
.PP
Including the \f4dial.h\f1
header file automatically includes the \f4termio.h\f1
header file.
.sp .5
An
\f4alarm\fP(2)
system call for 3600 seconds is made (and caught) within the
\f4dial\fP
module for the purpose of ``touching'' the \f4LCK..\fP file
and constitutes the device allocation semaphore for the terminal
device.
Otherwise,
\f4uucp\fP(1C)
may simply delete the \f4LCK..\fP entry on its 90-minute clean-up rounds.
The alarm may go off while the user program is in a
\f4read\fP(2)
or
\f4write\fP(2)
system call, causing an apparent error return.
If the user program expects to be around for an hour or more, error
returns from
\f4read\fPs
should be checked for \f4(errno==EINTR)\fP, and the
\f4read\fP
possibly reissued.
.\"	@(#)dial.3c	5.2 of 5/18/82
.Ee
