Family: table
Authors: KSB Braunsdorf
Mail: ksb@npcguild.org
Version: 1.8
Bugs: None known.

Introduction

The three wrappers wrapw, gtfw, and opal all use the same encoding to send tables of strings between each other. These functions implement those protocols.

Configuration

Provide either a standard machine.h or an in-line definition for:
#define TABLE_CHUNKS 16
This limits the number of strings sent per-call to writev(2). Larger values reduce the number of system calls made, a little.

The default is 16.

Synopsis

From mkcmd include the code in your command-line option parser.
from '"machine.h"'
from '"table.h"'
require "table.c"

Or you may explode any of the functions below, see the output of:

$ explode -t table.c
table.c	table*/.c
table.c	tableread.c	$Revision...
table.c	tablesend.c	$Revision...
table.c	tablerepeat.c	$Revision...
table.c	tabletovector.c	$Revision...
for current a list of possible targets.

Description

The functions below send and receive NULL terminated vectors of NUL terminated strings (like argv argument, or environ environment). There is an interface to convert the wire format back into a vector, or you can use it as a list of NUL terminate strings terminated by the empty string.

Provides

static const char acNoData[];
A constant string which represents an empty table (or string) on the wire.
static int SendTable(int iFd, const char **ppcTable, char *pcSize);
Send an argv-like vector of strings to the remote peer. Record the size of the wire encoding in the string provided (which should be at least 32 characters). An (char *)0 passed as pcSize just doesn't return the size to the caller.
static char *ReadTable(int iFd, char *pcSize/* 128 bytes at least */);
Receive a table from the peer connected on iFd. The table is returned as a catenation of the strings, not at an argv-like strucute. To convert it into a (char **), use TableToVector below. The data returned may be free(3)'d wnen you are done with it.
static int SendRepeat(int iFd, const char *psData, const char *pcSize);
Given that a peer received a table via ReadTable, the returned catenation may be resent to another peer, without any need for a decode/encode cycle. Pass the data and the size returned. If you don't have the size, the transmission stops at the first empty string.
static const char **TableToVector(const char *psTable, const char *pcSize);
Decode the encoded table into a (char **) vector. The unpacked vector may be free(3)'d when you are done with it. Note that the vector points into the catenation provided, so do not free it until you are done. Also the first pointer in the list is the original psTable.
static int SendString(int iFd, const char *pcData);
Send a single NUL termintad string, like the size above, to the peer. This sends a single string as a table of 1.

EXAMPLE

See the source directories for opal and wrapw.

Diagnostics

None.

See Also

The opal manual page, and the wrapw HTML document.

To Do List

Nothing.
$Id: table.html,v 1.11 2013/10/01 20:38:42 ksb Exp $