commands.3

NAME

commands - read and obey \n-terminated commands

SYNTAX

#include <commands.h>

int ctl_maxcmdlen;
int commands(&ss,c);

substdio ss;
struct commands c[];

DESCRIPTION

commands reads a series of commands from ss and follows the corresponding instructions listed in c.

commands returns 0 when it reaches end of file. It returns -1, setting errno appropriately, if it runs out of memory or has trouble reading ss. It returns -2 if the command length is too long. You can set the max command length by setting ctl_maxcmdlen.

Each command is terminated by \n. Partial final lines are ignored. If a command ends with \r, the \r is removed.

Each command contains a verb, consisting of zero or more non-space characters, followed optionally by one or more spaces and an argument.

Recognized verbs are listed in c. c is an array of one or more struct commands. Each struct has three components: char *verb; void *action(); and void *flush().

verb points to a \0-terminated string, interpreted without regard to case. If the command verb matches this string, commands calls action(arg), followed by flush() if flush is not the zero pointer. Here arg is a pointer to a \0-terminated string containing the argument (with any \0 inside the argument replaced by \n), or the empty string if there is no argument.

Exception: In the last struct in c, verb is the 0 pointer. commands uses this action for all unrecognized verbs.

ENGINEERING NOTES

The format accepted by commands has been copied from one Internet protocol to another. It is used in SMTP, FTP, POP, etc.

This does not mean it is a good format. It violates basic engineering principles. It has produced a continuing string of interoperability problems.

See http://pobox.com/~djb/proto/design.html for further comments.

EXAMPLE

If c is initialized to

   { { "help", usage, empty }


   , { "do", doit, 0 }


   , { 0, syntax, empty }


   }

and commands receives the input

   Do this


   undo  that


   HELP

then commands will call doit("this"), syntax("that"), empty(), usage(""), and empty().

SEE ALSO

substdio(3)