usr/src/man/man3nsl/dial.3nsl

   1 '\" te
   2 .\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DIAL 3NSL "Dec 30, 1996"
   8 .SH NAME
   9 dial, undial \- establish an outgoing terminal line connection
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR... ]
  14 #include <dial.h>
  15
  16 \fBint\fR \fBdial\fR(\fBCALL\fR \fIcall\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBundial\fR(\fBint\fR \fIfd\fR);
  22 .fi
  23
  24 .SH DESCRIPTION
  25 .sp
  26 .LP
  27 The \fBdial()\fR function returns a file-descriptor for a terminal line open
  28 for read/write. The argument to \fBdial()\fR is a \fBCALL\fR structure (defined
  29 in the header <\fBdial.h\fR>).
  30 .sp
  31 .LP
  32 When finished with the terminal line, the calling program must  invoke
  33 \fBundial()\fR to release the semaphore that has been set during the allocation
  34 of the terminal device.
  35 .sp
  36 .LP
  37 \fBCALL\fR is defined in the header <\fBdial.h\fR> and has the following
  38 members:
  39 .sp
  40 .in +2
  41 .nf
  42 struct termio *attr;      /* pointer to termio attribute struct */
  43 int           baud;        /* transmission data rate */
  44 int           speed;       /* 212A modem: low=300, high=1200 */
  45 char          *line;       /* device name for out-going line */
  46 char          *telno;    /* pointer to tel-no digits string */
  47 int           modem;       /* specify modem control for direct lines */
  48 char          *device;  /* unused */
  49 int           dev_len;  /* unused */
  50 .fi
  51 .in -2
  52
  53 .sp
  54 .LP
  55 The \fBCALL\fR element \fBspeed\fR is intended only for use with an outgoing
  56 dialed call, in which case its value should be the desired transmission baud
  57 rate.  The \fBCALL\fR element \fBbaud\fR is no longer used.
  58 .sp
  59 .LP
  60 If the desired terminal line is a direct line, a string pointer to its
  61 device-name should be placed in the \fBline\fR element in the \fBCALL\fR
  62 structure. Legal values for such terminal device names are kept in the
  63 \fBDevices\fR file. In this case, the value of the \fBbaud\fR element should be
  64 set to -1. This value will cause \fBdial\fR to determine the correct value from
  65 the \fB<Devices>\fR file.
  66 .sp
  67 .LP
  68 The \fBtelno\fR element is for a pointer to a character string representing the
  69 telephone number to be dialed. Such numbers may consist only of these
  70 characters:
  71 .sp
  72
  73 .sp
  74 .TS
  75 l l
  76 l l .
  77 0-9     dial 0-9
  78 *       dail  *
  79 #       dail  #
  80 =       wait for secondary dial tone
  81 -       delay for approximately 4 seconds
  82 .TE
  83
  84 .sp
  85 .LP
  86 The \fBCALL\fR element \fBmodem\fR is used to specify modem control for direct
  87 lines. This element should be non-zero if modem control is required. The
  88 \fBCALL\fR element \fBattr\fR is a pointer to a \fBtermio\fR structure, as
  89 defined in the header \fB<termio.h>\fR\&. A \fINULL\fR value for this pointer
  90 element may be passed to the \fBdial\fR function, but if such a structure is
  91 included, the elements specified in it will be set for the outgoing terminal
  92 line before the connection is established. This setting is often important for
  93 certain attributes such as parity and baud-rate.
  94 .sp
  95 .LP
  96 The \fBCALL\fR elements \fBdevice\fR and \fBdev_len\fR are no longer used. They
  97 are retained in the \fBCALL\fR structure for compatibility reasons.
  98 .SH RETURN VALUES
  99 .sp
 100 .LP
 101 On failure, a negative value indicating the reason for the failure will be
 102 returned. Mnemonics for these negative indices as listed here are defined in
 103 the header <\fBdial.h\fR>.
 104 .sp
 105 .in +2
 106 .nf
 107 INTRPT  \(mi1        /* interrupt occurred */
 108 D_HUNG  \(mi2        /* dialer hung (no return from write) */
 109 NO_ANS  \(mi3        /* no answer within 10 seconds */
 110 ILL_BD  \(mi4        /* illegal baud-rate */
 111 A_PROB  \(mi5        /* acu problem (open(\|) failure) */
 112 L_PROB  \(mi6        /* line problem (open(\|) failure) */
 113 NO_Ldv  \(mi7        /* can't open Devices file */
 114 DV_NT_A \(mi8        /* requested device not available */
 115 DV_NT_K \(mi9        /* requested device not known */
 116 NO_BD_A \(mi10       /* no device available at requested baud */
 117 NO_BD_K \(mi11       /* no device known at requested baud */
 118 DV_NT_E \(mi12       /* requested speed does not match */
 119 BAD_SYS \(mi13       /* system not in Systems file*/
 120 .fi
 121 .in -2
 122
 123 .SH FILES
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fB/etc/uucp/Devices\fR\fR
 128 .ad
 129 .sp .6
 130 .RS 4n
 131
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fB/etc/uucp/Systems\fR\fR
 138 .ad
 139 .sp .6
 140 .RS 4n
 141
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fB/var/spool/uucp/LCK..\fR\fItty-device\fR\fR
 148 .ad
 149 .sp .6
 150 .RS 4n
 151
 152 .RE
 153
 154 .SH ATTRIBUTES
 155 .sp
 156 .LP
 157 See \fBattributes\fR(5) for descriptions of the following attributes:
 158 .sp
 159
 160 .sp
 161 .TS
 162 box;
 163 c | c
 164 l | l .
 165 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 166 _
 167 MT-Level        Unsafe
 168 .TE
 169
 170 .SH SEE ALSO
 171 .sp
 172 .LP
 173 \fBuucp\fR(1C), \fBalarm\fR(2), \fBread\fR(2), \fBwrite\fR(2),
 174 \fBattributes\fR(5), \fBtermio\fR(7I)
 175 .SH NOTES
 176 .sp
 177 .LP
 178 Including the header <\fBdial.h\fR> automatically includes the header
 179 \fB<termio.h>\fR\&. An \fBalarm\fR(2) system call for 3600 seconds is made (and
 180 caught) within the \fBdial\fR module for the purpose of ``touching'' the
 181 \fBLCK..\fR file and constitutes the device allocation semaphore for the
 182 terminal device. Otherwise, \fBuucp\fR(1C) may simply delete the \fBLCK..\fR
 183 entry on its 90-minute clean-up rounds. The alarm may go off while the user
 184 program is in a \fBread\fR(2) or \fBwrite\fR(2) function, causing an apparent
 185 error return. If the user program expects to be around for an hour or more,
 186 error returns from \fBread()\fRs should be checked for \fB(errno==EINTR)\fR,
 187 and the \fBread()\fR possibly reissued.
 188 .sp
 189 .LP
 190 This interface is unsafe in multithreaded applications.  Unsafe interfaces
 191 should be called only from the main thread.