dial(3C)        UNIX System V(C Programming Language Utilities)        dial(3C)


NAME
      dial - establish an outgoing terminal line connection

SYNOPSIS
      #include <dial.h>

      int dial (CALL call);

      void undial (int fd);

DESCRIPTION
      dial 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 out-going line */
           char    *telno;        /* pointer to tel-no digits string */
           int     modem; /* specify modem control for direct lines */
           char    *device;       /* unused */
           int     devlen;       /* 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
      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
      value will cause dial to determine the correct value from the Devices
      file.





10/89                                                                    Page 1

dial(3C)        UNIX System V(C Programming Language Utilities)        dial(3C)


      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 non-zero 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 setting is often important
      for certain attributes such as parity and baud-rate.

      The CALL elements device and devlen are no longer used.  They are
      retained in the CALL structure for compatibility reasons.

FILES
      /etc/uucp/Devices
      /etc/uucp/Systems
      /var/spool/uucp/LCK..tty-device

SEE ALSO
      alarm(2), read(2), write(2).
      termio(7) in the System Administrator's Reference Manual.
      uucp(1C) in the User's Reference Manual.

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 dial.h header file.
           INTRPT  -1     /* interrupt occurred */
           DHUNG  -2     /* dialer hung (no return from write) */
           NOANS  -3     /* no answer within 10 seconds */
           ILLBD  -4     /* illegal baud-rate */
           APROB  -5     /* acu problem (open() failure) */
           LPROB  -6     /* line problem (open() failure) */
           NOLdv  -7     /* can't open Devices file */
           DVNTA -8     /* requested device not available */
           DVNTK -9     /* requested device not known */
           NOBDA -10    /* no device available at requested baud */
           NOBDK -11    /* no device known at requested baud */
           DVNTE -12    /* requested speed does not match */
           BADSYS -13    /* system not in Systems file*/

NOTES




Page 2                                                                    10/89

dial(3C)        UNIX System V(C Programming Language Utilities)        dial(3C)


      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.











































10/89                                                                    Page 3