1dial(3NSL)           Networking Services Library Functions          dial(3NSL)
2
3
4

NAME

6       dial, undial - establish an outgoing terminal line connection
7

SYNOPSIS

9       cc [ flag... ] file... -lnsl [ library... ]
10       #include <dial.h>
11
12       int dial(CALL call);
13
14
15       void undial(int fd);
16
17

DESCRIPTION

19       The  dial() function returns a file-descriptor for a terminal line open
20       for read/write. The argument to dial() is a CALL structure (defined  in
21       the header <dial.h>).
22
23
24       When  finished with the terminal line, the calling program must  invoke
25       undial() to release the semaphore that has been set during the  alloca‐
26       tion of the terminal device.
27
28
29       CALL is defined in the header <dial.h> and has the following members:
30
31         struct termio *attr;       /* pointer to termio attribute struct */
32         int           baud;    /* transmission data rate */
33         int           speed;        /* 212A modem: low=300, high=1200 */
34         char          *line;        /* device name for out-going line */
35         char          *telno;     /* pointer to tel-no digits string */
36         int           modem;        /* specify modem control for direct lines */
37         char          *device;   /* unused */
38         int           dev_len;   /* unused */
39
40
41
42       The CALL element speed is intended only for use with an outgoing dialed
43       call, in which case its value should be the desired  transmission  baud
44       rate.  The CALL element baud is no longer used.
45
46
47       If  the desired terminal line is a direct line, a string pointer to its
48       device-name should be placed in the line element in the CALL structure.
49       Legal  values  for  such  terminal device names are kept in the Devices
50       file. In this case, the value of the baud element should be set to  -1.
51       This  value  will  cause  dial  to determine the correct value from the
52       <Devices> file.
53
54
55       The telno element is for a pointer to a character  string  representing
56       the  telephone  number  to  be dialed. Such numbers may consist only of
57       these characters:
58
59
60
61
62       0-9                           dial 0-9
63       *                             dail  *
64       #                             dail  #
65       ──────────────────────────────wait for secondary dial tone
66
67       -                             delay for approximately 4 seconds
68
69
70
71       The CALL element modem is used to  specify  modem  control  for  direct
72       lines.  This  element  should be non-zero if modem control is required.
73       The CALL element attr is a pointer to a termio structure, as defined in
74       the  header  <termio.h>.  A  NULL value for this pointer element may be
75       passed to the dial function, but if such a structure is  included,  the
76       elements  specified  in  it  will be set for the outgoing terminal line
77       before the connection is established. This setting is  often  important
78       for certain attributes such as parity and baud-rate.
79
80
81       The  CALL  elements  device  and  dev_len  are no longer used. They are
82       retained in the CALL structure for compatibility reasons.
83

RETURN VALUES

85       On failure, a negative value indicating the reason for the failure will
86       be  returned.  Mnemonics  for these negative indices as listed here are
87       defined in the header <dial.h>.
88
89         INTRPT  −1        /* interrupt occurred */
90         D_HUNG  −2        /* dialer hung (no return from write) */
91         NO_ANS  −3        /* no answer within 10 seconds */
92         ILL_BD  −4        /* illegal baud-rate */
93         A_PROB  −5        /* acu problem (open() failure) */
94         L_PROB  −6        /* line problem (open() failure) */
95         NO_Ldv  −7        /* can't open Devices file */
96         DV_NT_A −8        /* requested device not available */
97         DV_NT_K −9        /* requested device not known */
98         NO_BD_A −10       /* no device available at requested baud */
99         NO_BD_K −11       /* no device known at requested baud */
100         DV_NT_E −12       /* requested speed does not match */
101         BAD_SYS −13       /* system not in Systems file*/
102
103

FILES

105       /etc/uucp/Devices
106
107
108
109
110       /etc/uucp/Systems
111
112
113
114
115       /var/spool/uucp/LCK..tty-device
116
117
118
119

ATTRIBUTES

121       See attributes(5) for descriptions of the following attributes:
122
123
124
125
126       ┌─────────────────────────────┬─────────────────────────────┐
127       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
128       ├─────────────────────────────┼─────────────────────────────┤
129       │MT-Level                     │Unsafe                       │
130       └─────────────────────────────┴─────────────────────────────┘
131

SEE ALSO

133       uucp(1C), alarm(2), read(2), write(2), attributes(5), termio(7I)
134

NOTES

136       Including  the  header  <dial.h>  automatically  includes  the   header
137       <termio.h>.  An  alarm(2)  system  call  for  3600 seconds is made (and
138       caught) within the dial module for  the  purpose  of  ``touching''  the
139       LCK.. file and constitutes the device allocation semaphore for the ter‐
140       minal device. Otherwise, uucp(1C) may simply delete the LCK.. entry  on
141       its 90-minute clean-up rounds. The alarm may go off while the user pro‐
142       gram is in a read(2) or write(2) function, causing  an  apparent  error
143       return.  If  the user program expects to be around for an hour or more,
144       error returns from read()s should be checked  for  (errno==EINTR),  and
145       the read() possibly reissued.
146
147
148       This  interface is unsafe in multithreaded applications.  Unsafe inter‐
149       faces should be called only from the main thread.
150
151
152
153SunOS 5.11                        30 Dec 1996                       dial(3NSL)
Impressum