sys/man/2/dial

   1 .TH DIAL 2
   2 .SH NAME
   3 dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- make and break network connections
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .B
  10 int   dial(char *addr, char *local, char *dir, int *cfdp)
  11 .PP
  12 .B
  13 int   hangup(int ctl)
  14 .PP
  15 .B
  16 int   announce(char *addr, char *dir)
  17 .PP
  18 .B
  19 int   listen(char *dir, char *newdir)
  20 .PP
  21 .B
  22 int   accept(int ctl, char *dir)
  23 .PP
  24 .B
  25 int   reject(int ctl, char *dir, char *cause)
  26 .PP
  27 .B
  28 char* netmkaddr(char *addr, char *defnet, char *defservice)
  29 .PP
  30 .B
  31 void  setnetmtpt(char *to, int tolen, char *from)
  32 .PP
  33 .B
  34 NetConnInfo*  getnetconninfo(char *conndir, int fd)
  35 .PP
  36 .B
  37 void freenetconninfo(NetConnInfo*)
  38 .SH DESCRIPTION
  39 For these routines,
  40 .I addr
  41 is a network address of the form
  42 .IB network ! netaddr ! service\f1,
  43 .IB network ! netaddr\f1,
  44 or simply
  45 .IR netaddr .
  46 .I Network
  47 is any directory listed in
  48 .B /net
  49 or the special token,
  50 .BR net .
  51 .B Net
  52 is a free variable that stands for any network in common
  53 between the source and the host
  54 .IR netaddr .
  55 .I Netaddr
  56 can be a host name, a domain name, a network address,
  57 or a meta-name of the form
  58 .BI $ attribute\f1,
  59 which
  60 is replaced by
  61 .I value
  62 from the value-attribute pair
  63 .IB attribute = value
  64 most closely associated with the source host in the
  65 network data base (see
  66 .IR ndb (6)).
  67 .PP
  68 If a connection attempt is successful and
  69 .I dir
  70 is non-zero,
  71 the path name of a
  72 .I line directory
  73 that has files for accessing the connection
  74 is copied into
  75 .IR dir .
  76 The path name is guaranteed to be less than 40
  77 bytes long.
  78 One line directory exists for each possible connection.
  79 The
  80 .B data
  81 file in the line directory should be used to communicate with the destination.
  82 The
  83 .B ctl
  84 file in the line directory can be used to send commands to the line.
  85 See
  86 .IR ip (3)
  87 for messages that can be written to the
  88 .B ctl
  89 file.
  90 The last close of the
  91 .B data
  92 or
  93 .B ctl
  94 file will close the connection.
  95 .PP
  96 .I Dial
  97 makes a call to destination
  98 .I addr
  99 on a multiplexed network.
 100 If the network in
 101 .I addr
 102 is
 103 .BR net ,
 104 .I dial
 105 will try all addresses on networks in common between source
 106 and destination until a call succeeds.
 107 It returns a file descriptor open for reading and writing the
 108 .B data
 109 file in the line directory.
 110 The
 111 .B addr
 112 file in the line directory contains the address called.
 113 If the network allows the local address to be set,
 114 as is the case with UDP and TCP port numbers, and
 115 .IR local
 116 is non-zero, the local address will be set to
 117 .IR local .
 118 If
 119 .I cfdp
 120 is non-zero,
 121 .BI * cfdp
 122 is set to a file descriptor open for reading and
 123 writing the control file.
 124 .PP
 125 .I Hangup
 126 is a means of forcing a connection to hang up without
 127 closing the
 128 .B ctl
 129 and
 130 .B data
 131 files.
 132 .P
 133 .I Announce
 134 and
 135 .I listen
 136 are the complements of
 137 .IR dial .
 138 .I Announce
 139 establishes a network
 140 name to which calls can be made, and returns an open
 141 .B ctl
 142 file.
 143 The
 144 .I netaddr
 145 used in announce may be a local address or an asterisk,
 146 to indicate all local addresses, e.g.
 147 .BR tcp!*!echo .
 148 The
 149 .I listen
 150 routine takes as its first argument the
 151 .I dir
 152 of a previous
 153 .IR announce .
 154 When a call is received,
 155 .I listen
 156 returns an open
 157 .B ctl
 158 file for the line the call was received on.
 159 It sets
 160 .I newdir
 161 to the path name of the new line directory.
 162 .I Accept
 163 accepts a call received by
 164 .IR listen ,
 165 while
 166 .I reject
 167 refuses the call because of
 168 .IR cause .
 169 .I Accept
 170 returns a file descriptor for the data file opened
 171 .BR ORDWR .
 172 .PP
 173 .I Netmkaddr
 174 makes an address suitable for dialing or announcing.
 175 It takes an address along with a default network and service to use
 176 if they are not specified in the address.
 177 It returns a pointer to static data holding the actual address to use.
 178 .PP
 179 .I Getnetconninfo
 180 returns a structure containing information about a
 181 network connection.  The structure is:
 182 .EX
 183   typedef struct NetConnInfo NetConnInfo;
 184   struct NetConnInfo
 185   {
 186         char    *dir;           /* connection directory */
 187         char    *root;          /* network root */
 188         char    *spec;          /* binding spec */
 189         char    *lsys;          /* local system */
 190         char    *lserv;         /* local service */
 191         char    *rsys;          /* remote system */
 192         char    *rserv;         /* remote service */
 193         char    *laddr;         /* local address */
 194         char    *raddr;         /* remote address */
 195   };
 196 .EE
 197 .PP
 198 The information is obtained from the connection directory,
 199 .IR conndir .
 200 If
 201 .I conndir
 202 is nil, the directory is obtained by performing
 203 .IR fd2path (2)
 204 on
 205 .IR fd .
 206 .I Getnetconninfo
 207 returns either a completely specified structure, or
 208 nil if either the structure can't be allocated or the
 209 network directory can't be determined.
 210 The structure
 211 is freed using
 212 .IR freenetconninfo .
 213 .PP
 214 .I Setnetmtpt
 215 copies the name of the network mount point into
 216 the buffer
 217 .IR to ,
 218 whose length is
 219 .IR tolen .
 220 It exists to merge two pre-existing conventions for specifying
 221 the mount point.
 222 Commands that take a network mount point as a parameter
 223 (such as
 224 .BR dns ,
 225 .BR cs
 226 (see
 227 .IR ndb (8)),
 228 and
 229 .IR ipconfig (8))
 230 should now call
 231 .IR setnetmtpt .
 232 If
 233 .I from
 234 is
 235 .BR nil ,
 236 the mount point is set to the default,
 237 .BR /net .
 238 If
 239 .I from
 240 points to a string starting with a slash,
 241 the mount point is that path.
 242 Otherwise, the mount point is the string pointed to by
 243 .I from
 244 appended to the string
 245 .BR /net .
 246 The last form is obsolete and it should be avoided.
 247 It exists only to aid in conversion.
 248 .SH EXAMPLES
 249 Make a call and return an open file descriptor to
 250 use for communications:
 251 .IP
 252 .EX
 253 int callkremvax(void)
 254 {
 255         return dial("kremvax", nil, nil, nil);
 256 }
 257 .EE
 258 .PP
 259 Call the local authentication server:
 260 .IP
 261 .EX
 262 int dialauth(char *service)
 263 {
 264         return dial(netmkaddr("$auth", nil, service), nil, nil, nil);
 265 }
 266 .EE
 267 .PP
 268 Announce as
 269 .B kremvax
 270 on TCP/IP and
 271 loop forever receiving calls and echoing back
 272 to the caller anything sent:
 273 .IP
 274 .EX
 275 int
 276 bekremvax(void)
 277 {
 278         int dfd, acfd, lcfd;
 279         char adir[40], ldir[40];
 280         int n;
 281         char buf[256];
 282
 283         acfd = announce("tcp!*!7", adir);
 284         if(acfd < 0)
 285                 return -1;
 286         for(;;){
 287                 /* listen for a call */
 288                 lcfd = listen(adir, ldir);
 289                 if(lcfd < 0)
 290                         return -1;
 291                 /* fork a process to echo */
 292                 switch(fork()){
 293                 case -1:
 294                         perror("forking");
 295                         close(lcfd);
 296                         break;
 297                 case 0:
 298                         /* accept the call and open the data file */
 299                         dfd = accept(lcfd, ldir);
 300                         if(dfd < 0)
 301                                 return -1;
 302
 303                         /* echo until EOF */
 304                         while((n = read(dfd, buf, sizeof(buf))) > 0)
 305                                 write(dfd, buf, n);
 306                         exits(nil);
 307                 default:
 308                         close(lcfd);
 309                         break;
 310                 }
 311         }
 312 }
 313 .EE
 314 .SH SOURCE
 315 .BR /sys/src/libc/9sys ,
 316 .B /sys/src/libc/port
 317 .SH "SEE ALSO"
 318 .IR auth (2),
 319 .IR ip (3),
 320 .IR ndb (8)
 321 .SH DIAGNOSTICS
 322 .IR Dial ,
 323 .IR announce ,
 324 and
 325 .I listen
 326 return \-1 if they fail.
 327 .I Hangup
 328 returns nonzero if it fails.