DIAL(3C)                STANDARD C LIBRARY               DIAL(3C)


NAME
     dial -- establish an out-going, terminal-line connection


SYNOPSIS
     #include <dial.h>

     int dial(CALL call);

     void undial(int fd);


DESCRIPTION
     dial returns a file descriptor (fd) for a terminal line that
     is 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  was  set
     during the allocation of the terminal device.

     The  definition  of  CALL  in the <dial.h> header file is as
     follows.

       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; /* hold the device name making a connec-
                         tion */
           int  dev_len; /*  device  length making the connection
                         */
       } CALL;


     The CALL element speed is intended only for use with an out-
     going  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.

     The  113A  modem  or the low-speed setting of the 212A modem
     transmits at any rate between 0  and  300  bits   per   sec-
     ond.   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 the baud rate to 110 and
     the speed to 300 (or 1200).  However, if the speed is set to
     1200 baud, the baud rate must be set to high (1200).



SUPER-UX            Last change: Nov 18, 1996                   1





DIAL(3C)                STANDARD C LIBRARY               DIAL(3C)


     If  the  desired  terminal  line  is a direct line, a string
     pointer to its device name should be placed in the line ele-
     ment  in the CALL structure.  Legal values for such terminal
     device names are kept in the L-devices file.  In this  case,
     the  value of the baud element need not be specified because
     it is determined from the L-devices file.

     The telno element is for a pointer  to  a  character  string
     representing  the  telephone number to be dialed.  Such num-
     bers may consist only of symbols described  on  the  acu(7).
     The termination symbol is supplied by dial and should not be
     included in the telno string passed  to  dial  in  the  CALL
     structure.

     The  CALL element modem is used to specify modem control for
     direct lines.  This element should be non-zero if modem con-
     trol  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 can be passed to dial,
     but if such a structure is included, the elements  specified
     in it are set for the outgoing terminal line before the con-
     nection is established.  This is often important for certain
     attributes such as parity and baud rate.

     The  CALL  element  device  is  used to hold the device name
     (cul..) that establishes the connection.  The  CALL  element
     dev_len is the length of the device name that is copied into
     the array device.


FILES
     /usr/lib/uucp/L-devices
     /usr/spool/uucp/LCK..tty-device


SEE ALSO
     alarm(2), read(2), write(2), termio(7)


DIAGNOSTICS
     On failure, a negative value indicating the reason  for  the
     failure  is  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 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 LDEVS 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 */



SUPER-UX            Last change: Nov 18, 1996                   2





DIAL(3C)                STANDARD C LIBRARY               DIAL(3C)


        NO_BD_K -11 /* no device known at requested baud */


WARNINGS
     The dial(3C)  library  function  is   not  compatible   with
     Basic Networking Utilities on UNIX System V Release 2.0.

     Including  the  <dial.h>  header file automatically includes
     the <termio.h> header file.

     The previous routine use <stdio.h>, causing it  to  increase
     the  size  of programs more than might be expected (when not
     otherwise using standard I/O).


BUGS
     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) can
     simply delete the LCK..  entry  on  its  90-minute  clean-up
     rounds.  The alarm can 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.































SUPER-UX            Last change: Nov 18, 1996                   3