Back to libut API Reference


    #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.

Return value

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;
        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 <>