DIAL(3)

💅 DIAL(3) — Library Functions Manual 💅

okay bestie, welcome to the DIAL(3) page from the Library Functions Manual. it's giving network-connection core lore: making calls, announcing yourself, listening, accepting, rejecting, and parsing addresses. every single detail is below, no cap. 🫶

🌸 NAME 🌸

dial, announce, listen, accept, reject, netmkaddr, getnetconninfo, freenetconninfo, dialparse — make and break network connections. periodt. 💖

✨ SYNOPSIS ✨

#include <u.h>
#include <libc.h>

int   dial(char *addr, char *local, char *dir, int *cfdp)

int   announce(char *addr, char *dir)

int   listen(char *dir, char *newdir)

int   accept(int ctl, char *dir)

int   reject(int ctl, char *dir, char *cause)

char* netmkaddr(char *addr, char *defnet, char *defservice)

NetConnInfo*  getnetconninfo(char *dir, int fd)

void freenetconninfo(NetConnINfo*)

int   dialparse(char *addr, char **net, char **unix,
                 void *host, int *port)

🦋 DESCRIPTION 🦋

okay so for all these routines, addr is a network address in one of these shapes:

• network!netaddr!service
• network!netaddr
• just netaddr

network is tcp, udp, unix, or the special token net. net is a free variable that stands for any network in common between the source and the host netaddr. netaddr can be a host name, a domain name, or a network address. iykyk. 💫

On Plan 9, the dir argument is a path name to a line directory that has files for accessing the connection. to keep the same function signatures, the Unix port of these routines uses strings of the form /dev/fd/n instead of line directory paths. these strings should be treated as opaque data and ignored. 🙈

• dial — makes a call to destination addr on a multiplexed network. if the network in addr is net, dial will try in succession all networks in common between source and destination until a call succeeds. it returns a file descriptor open for reading and writing the call. if the network allows the local address to be set, as is the case with UDP and TCP port numbers, and local is non-zero, the local address will be set to local. dial's dir and cfdp arguments are not supported and must be zero. 🚨
• announce and listen — the complements of dial. announce establishes a network name to which calls can be made. like dial, announce returns an open ctl file. the netaddr used in announce may be a local address or an asterisk, to indicate all local addresses, e.g. tcp!*!echo. the listen routine takes as its first argument the dir of a previous announce. when a call is received, listen returns an open ctl file for the line the call was received on. it sets newdir to the path name of the new line directory. ✨
• accept — accepts a call received by listen. returns a file descriptor for the data file opened ORDWR. 👑
• reject — refuses the call because of cause. 💅
• netmkaddr — makes an address suitable for dialing or announcing. it takes an address along with a default network and service to use if they are not specified in the address. it returns a pointer to static data holding the actual address to use. netmkaddr also translates Unix conventions into Plan 9 syntax: if addr is the name of a local file or Unix domain socket, netmkaddr will return unix!addr; if addr is of the form host:port, netmkaddr will return net!host!port. 🎀
• dialparse — parses a network address as described above into a network name, a Unix domain socket address, an IP host address, and an IP port number. 🧚
• getnetconninfo — returns a structure containing information about a network connection. the structure is:

typedef struct NetConnInfo NetConnInfo;
struct NetConnInfo
{
   char *dir;          /* connection directory */
   char *root;         /* network root */
   char *spec;         /* binding spec */
   char *lsys;         /* local system */
   char *lserv;        /* local service */
   char *rsys;         /* remote system */
   char *rserv;        /* remote service */
   char *laddr;        /* local address */
   char *raddr;        /* remote address */
};

the information is obtained from the line directory' dir, or if dirisnil, from the connection file descriptor fd. getnetconninforeturns either a completely specified structure, ornilif either the structure can't be allocated or the network directory can't be determined. the structure is freed usingfreenetconninfo`. 🌈

🎀 EXAMPLES 🎀

Make a call and return an open file descriptor to use for communications:

int callkremvax(void)
{
     return dial("kremvax", 0, 0, 0);
}

Connect to a Unix socket served by acme(4):

int dialacme(void)
{
     return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0);
}

Announce as kremvax on TCP/IP and loop forever receiving calls and echoing back to the caller anything sent:

int
bekremvax(void)
{
     int dfd, acfd, lcfd;
     char adir[40], ldir[40];
     int n;
     char buf[256];

     acfd = announce("tcp!*!7", adir);
     if(acfd < 0)
          return -1;
     for(;;){
          /* listen for a call */
          lcfd = listen(adir, ldir);
          if(lcfd < 0)
               return -1;
          /* fork a process to echo */
          switch(fork()){
          case -1:
               perror("forking");
               close(lcfd);
               break;
          case 0:
               /* accept the call and open the data file */
               dfd = accept(lcfd, ldir);
               if(dfd < 0)
                    return -1;

               /* echo until EOF */
               while((n = read(dfd, buf, sizeof(buf))) > 0)
                    write(dfd, buf, n);
               exits(0);
          default:
               close(lcfd);
               break;
          }
     }
}

🌱 SOURCE 🌱

• /src/lib9/dial.c
• /src/lib9/announce.c
• /src/lib9/_p9dialparse.c
• /src/lib9/getnetconn.c

🚦 DIAGNOSTICS 🚦

dial, announce, and listen return -1 if they fail. 😭

💀 BUGS 💀

To avoid name conflicts with the underlying system, dial, announce, listen, netmkaddr, and reject are preprocessor macros defined as p9dial, p9announce, and so on; see intro(3). 🙈

💖 and that's the whole DIAL(3) page from the Library Functions Manual — the footer/version marker is just DIAL(3), and no date is listed, so that's the source/version/date lore we have. bye bestie, go make and break some network connections 🫶✨