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.
 141 Like
 142 .IR dial ,
 143 .I announce
 144 returns an open
 145 .B ctl
 146 file.
 147 The
 148 .I netaddr
 149 used in announce may be a local address or an asterisk,
 150 to indicate all local addresses, e.g.
 151 .BR tcp!*!echo .
 152 The
 153 .I listen
 154 routine takes as its first argument the
 155 .I dir
 156 of a previous
 157 .IR announce .
 158 When a call is received,
 159 .I listen
 160 returns an open
 161 .B ctl
 162 file for the line the call was received on.
 163 It sets
 164 .I newdir
 165 to the path name of the new line directory.
 166 .I Accept
 167 accepts a call received by
 168 .IR listen ,
 169 while
 170 .I reject
 171 refuses the call because of
 172 .IR cause .
 173 .I Accept
 174 returns a file descriptor for the data file opened
 175 .BR ORDWR .
 176 .PP
 177 .I Netmkaddr
 178 makes an address suitable for dialing or announcing.
 179 It takes an address along with a default network and service to use
 180 if they are not specified in the address.
 181 It returns a pointer to static data holding the actual address to use.
 182 .PP
 183 .I Getnetconninfo
 184 returns a structure containing information about a
 185 network connection.  The structure is:
 186 .EX
 187   typedef struct NetConnInfo NetConnInfo;
 188   struct NetConnInfo
 189   {
 190         char    *dir;           /* connection directory */
 191         char    *root;          /* network root */
 192         char    *spec;          /* binding spec */
 193         char    *lsys;          /* local system */
 194         char    *lserv;         /* local service */
 195         char    *rsys;          /* remote system */
 196         char    *rserv;         /* remote service */
 197         char    *laddr;         /* local address */
 198         char    *raddr;         /* remote address */
 199   };
 200 .EE
 201 .PP
 202 The information is obtained from the connection directory,
 203 .IR conndir .
 204 If
 205 .I conndir
 206 is nil, the directory is obtained by performing
 207 .IR fd2path (2)
 208 on
 209 .IR fd .
 210 .I Getnetconninfo
 211 returns either a completely specified structure, or
 212 nil if either the structure can't be allocated or the
 213 network directory can't be determined.
 214 The structure
 215 is freed using
 216 .IR freenetconninfo .
 217 .PP
 218 .I Setnetmtpt
 219 copies the name of the network mount point into
 220 the buffer
 221 .IR to ,
 222 whose length is
 223 .IR tolen .
 224 It exists to merge two pre-existing conventions for specifying
 225 the mount point.
 226 Commands that take a network mount point as a parameter
 227 (such as
 228 .BR dns ,
 229 .BR cs
 230 (see
 231 .IR ndb (8)),
 232 and
 233 .IR ipconfig (8))
 234 should now call
 235 .IR setnetmtpt .
 236 If
 237 .I from
 238 is
 239 .BR nil ,
 240 the mount point is set to the default,
 241 .BR /net .
 242 If
 243 .I from
 244 points to a string starting with a slash,
 245 the mount point is that path.
 246 Otherwise, the mount point is the string pointed to by
 247 .I from
 248 appended to the string
 249 .BR /net .
 250 The last form is obsolete and is should be avoided.
 251 It exists only to aid in conversion.
 252 .SH EXAMPLES
 253 Make a call and return an open file descriptor to
 254 use for communications:
 255 .IP
 256 .EX
 257 int callkremvax(void)
 258 {
 259         return dial("kremvax", nil, nil, nil);
 260 }
 261 .EE
 262 .PP
 263 Call the local authentication server:
 264 .IP
 265 .EX
 266 int dialauth(char *service)
 267 {
 268         return dial(netmkaddr("$auth", nil, service), nil, nil, nil);
 269 }
 270 .EE
 271 .PP
 272 Announce as
 273 .B kremvax
 274 on TCP/IP and
 275 loop forever receiving calls and echoing back
 276 to the caller anything sent:
 277 .IP
 278 .EX
 279 int
 280 bekremvax(void)
 281 {
 282         int dfd, acfd, lcfd;
 283         char adir[40], ldir[40];
 284         int n;
 285         char buf[256];
 286
 287         acfd = announce("tcp!*!7", adir);
 288         if(acfd < 0)
 289                 return -1;
 290         for(;;){
 291                 /* listen for a call */
 292                 lcfd = listen(adir, ldir);
 293                 if(lcfd < 0)
 294                         return -1;
 295                 /* fork a process to echo */
 296                 switch(fork()){
 297                 case -1:
 298                         perror("forking");
 299                         close(lcfd);
 300                         break;
 301                 case 0:
 302                         /* accept the call and open the data file */
 303                         dfd = accept(lcfd, ldir);
 304                         if(dfd < 0)
 305                                 return -1;
 306
 307                         /* echo until EOF */
 308                         while((n = read(dfd, buf, sizeof(buf))) > 0)
 309                                 write(dfd, buf, n);
 310                         exits(nil);
 311                 default:
 312                         close(lcfd);
 313                         break;
 314                 }
 315         }
 316 }
 317 .EE
 318 .SH SOURCE
 319 .BR /sys/src/libc/9sys ,
 320 .B /sys/src/libc/port
 321 .SH "SEE ALSO"
 322 .IR auth (2),
 323 .IR ip (3),
 324 .IR ndb (8)
 325 .SH DIAGNOSTICS
 326 .IR Dial ,
 327 .IR announce ,
 328 and
 329 .I listen
 330 return \-1 if they fail.
 331 .I Hangup
 332 returns nonzero if it fails.