dials(3N)

Synopsis

#include <dial.h>

int dials(calls_t *call, calls_t **ret_call, dial_status_t *dstatus);

void undials(int fd, calls_t *ret_call);

Description

When it is finished with a terminal line, the calling program should call undials to add HUPCL to the c_flags of the termios structure for that line.

The arguments to dials are defined as follows:

call

The definition of calls_t in the dial.h header file is:

typedef struct {
	long	flags;           /* reserved for future use */
	struct termios *attr;    /* pointer to termios attribute struct */
	int	speed;           /* speed used for the link */
	char	*device_name;    /* device name for outgoing line */
	char	*telno;          /* telephone number to dial */
	char	*caller_telno;	 /* the calling telephone number */
	char	*sysname;        /* system name to use from the Systems file */
	unsigned short function; /* bit field for switching on required functions */
	char	*class;	         /* the device to search for in Type field of
				    the /etc/uccp/Devices file */
	char	*protocol;       /* protocol string as specified in Type field of
				    the /etc/uccp/Systems file */
	int	pinfo_len;       /* size of pinfo (in bytes) */
	void	*pinfo;	         /* pointer to protocol-specific information */
} calls_t;

The elements of the calls_t structure are defined below:

flags

This field must be 0, and is reserved for future use.

attr

A pointer to a termios structure, as defined in the termios.h header file. A NULL value for this pointer element may be passed to the dials 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.

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.

A value of -1 specifies any speed.

device_name

If the requested terminal line is a direct line, this field should contain a string pointer to its device name. Legal values for such terminal device names are kept in the Devices(4bnu) file. In this case, the value of the speed element should be set to -1. This value will cause dials 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

caller_telno

This field is typically set for ISDN devices so that isdndialer can map the telephone number to the B channels on the ISDN adapters. This allows the application to select a B channel for placing outgoing calls.

sysname

The name of the system to call. This field is filled in by the application and is optional.

function

This is a bit mask that represents functions to turn on or off. This field defaults to 0, which is equivalent to the cu(1bnu) service. The following bit masks are defined in dial.h:

FUNC_NULL	0x00	/* cu functionality (default) */
FUNC_CHAT	0x80	/* allows chat scripts to be executed */
FUNC_TX		0x40	/* sets the open line modes to transfer files */

To enable uucico(1Mbnu) functionality, set this field to FUNC_CHAT | FUNC_TX.

class

This supplies dials 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

This 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.

pinfo_len

pinfo

ret_call

The Connection Server returns this data to the calling application.

dstatus

The Connection Server returns this data.

The definition of dial_status_t is:

typedef struct {
	int	status_code;		/* value defined in dial.h */
	dial_service_t	service_type;	/* ennumerated services available */
} dial_status_t;

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 return from write) */
   NO_ANS	 -3	/* no answer (caller script 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	/* connection server related error */
   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 dials 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.

dials is an interface call to the Connection Server daemon. The Connection Server establishes the connection and passes back the file descriptor to dials. 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.