Networking Services Library Functions                  dial(3NSL)



NAME
     dial, undial - establish an outgoing terminal  line  connec-
     tion

SYNOPSIS
     cc [ flag... ] file... -lnsl [ library... ]
     #include 

     int dial(CAL call);


     void undial(int fd);


DESCRIPTION
     The dial() function returns a file-descriptor for a terminal
     line  open  for read/write. The argument to dial() is a CAL
     structure (defined in the header ).


     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.


     CAL is defined in the header  and has the following
     members:

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



     The CAL element speed is intended only for use with an out-
     going  dialed  call,  in  which case its value should be the
     desired transmission baud rate.  The CAL element baud is no
     longer used.


     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 CAL 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
      file.



SunOS 5.11          Last change: 30 Dec 1996                    1






Networking Services Library Functions                  dial(3NSL)



     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
     *                             dail  *
     #                             dail  #
      wait for secondary dial tone
     -                             delay for approximately 4 seconds



     The CAL element modem is used to specify modem control  for
     direct  lines. This element should be non-zero if modem con-
     trol is required. The CAL element attr is a  pointer  to  a
     termio  structure,  as  defined  in the header . A
     NUL value for this pointer element may  be  passed  to  the
     dial function, but if such a structure is included, the ele-
     ments 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 CAL elements device and devlen  are  no  longer  used.
     They  are  retained  in the CAL structure for compatibility
     reasons.

RETURN VALUES
     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 header .

       INTRPT  -1        /* interrupt occurred */
       DHUNG  -2        /* dialer hung (no return from write) */
       NOANS  -3        /* no answer within 10 seconds */
       ILBD  -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*/


FILES




SunOS 5.11          Last change: 30 Dec 1996                    2






Networking Services Library Functions                  dial(3NSL)



     /etc/uucp/Devices




     /etc/uucp/Systems




     /var/spool/uucp/LCK..tty-device




ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     Unsafe                      
    


SEE ALSO
     uucp(1C),  alarm(2),   read(2),   write(2),   attributes(5),
     termio(7I)

NOTES
     Including the header    automatically  includes  the
     header  . 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) function, causing an apparent
     error return. If the user program expects to be  around  for
     an  hour  or  more,  error  returns  from  read()s should be
     checked for (errno==EINTR), and the  read()  possibly  reis-
     sued.


     This interface  is  unsafe  in  multithreaded  applications.
     Unsafe  interfaces  should  be  called  only  from  the main
     thread.





SunOS 5.11          Last change: 30 Dec 1996                    3