#include "libut/ut.h"
int UT_shl_cmd_create( char *name, char *desc, UT_shlcmd *cb, UT_helpcb *hb);
This function creates a new command within the control port interpreter.
The command has the given name and description desc. Both are copied and silently truncated if too long. The description desc is used only in the output of the control port help command.
The cb argument specifies the callback which implements the command. See the COMMAND CALLBACK section below.
The final argument hb, if non-NULL, specifies a callback that prints detailed help (usage information) for the command. See the HELP CALLBACK below.
The callback that implements a command must have this prototype:
int (UT_shlcmd)( int argc ,char *argv[] );
Command callbacks are invoked either because a user entered the command in the control port, or because libut is parsing a configuration file containing that command.
The callback receives the two parameters argc and argv which are analogous to the arguments to main().
The callback may produce output to the control port using UT_shlf(3), or
UT_shle(3) for error output.
The callback must return either SHL_OK or SHL_ERROR.
Returning SHL_OK causes the output text previously constructed
using UT_shlf(3) to be written out to the control port.
If SHL_ERROR is returned instead, the error text previously constructed using
UT_shle(3) is written out to the control port, and an error is logged.
The callback that is invoked to provide detailed help (when help command
is issued in the control port) must have this prototype:
int (UT_helpcb)( int argc ,char *argv[] );
The argc and argv parameters are analogous to those passed to main(). Note that they do not include ``help'' itself. E.g., if a user enters:
help foo -h
then the help callback for foo is invoked with argc set to 2, with argv[0] pointing to ``foo'' and argv[1] pointing to ``-h''.
The help callback should use UT_shlf(3) to give usage instructions for the
command named in argv[0] and then return. The return value is ignored.
This function always returns 0.
There is no checking to see if you're redefining an existing command.
The help control port command lists all the commands that have been created using this function.
If libut invokes a command callback because it is parsing a configuration file
containing that command, any output that the command generates using UT_shlf(3)
or UT_shle(3) is logged (since there is no control port connection to which it
can be written). When logged, newlines are converted to '\' characters. Note
also that the long lines are truncated when logged.
The implementation of a control port command that prints the current time is:
#include <time.h>
int time_cmd(int argc, char *argv[]) {
time_t tm;
time(&tm);
UT_shlf("current time is %s\n", ctime(&tm));
return SHL_OK;
}
The code that creates the ``time'' command is:
UT_shl_cmd_create( "time", "show current time", time_cmd, NULL);
UT_shl_hdr(3), UT_shlf(3), UT_shle(3)
Troy D. Hanson <thanson@users.sourceforge.net>