dial(3N)

Synopsis

#include <dial.h>

int dial(CALL call);

void undial(int fd);

Description

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;

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.

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(4bnu) 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 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 the 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(1bnu) 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

   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 */

References

Notices

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(1bnu) 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 the file descriptor to dial. See cs(1Mbnu) 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 do not have to (and should not be) removed by the user.

Backward compatibility