VxWorks API Reference : USB libraries
cmdParser [USB] - Command line parser routines.
PromptAndExecCmd( ) - Prompt for a command and execute it.
KeywordMatch( ) - Compare keywords
ExecCmd( ) - Execute the command line
SkipSpace( ) - Skips leading white space in a string
TruncSpace( ) - Truncates string to eliminate trailing whitespace
GetNextToken( ) - Retrieves the next token from an input string
GetHexToken( ) - Retrieves value of hex token
CmdParserHelpFunc( ) - Displays list of supported commands
CmdParserExitFunc( ) - Terminates parser execution
This file includes a collection of command-line parsing functions which are useful in the creation of command line utilities, such as bus exercisers.
There are three groups of functions defined by this library. The first is a collection of general string parser functions, such as functions to eliminate white space, functions to strip tokens out of a string, and so forth.
The second set of functions drive the actual parsing process. In order to use this second set of functions, clients must construct a table of CMD_DESCR structures which define the commands to be recognized by the parser. A brief example of such a table is shown below.
CMD_DESCR Commands [] = { {"Help", 4, "Help/?", "Displays list of commands.", CmdParserHelpFunc}, {"?", 1, NULL, NULL, CmdParserHelpFunc}, {"Exit", 4, "Exit", "Exits program.", CmdParserExitFunc}, {NULL, 0, NULL, NULL, NULL} };The first field is the keyword for the command. The second field specifies the number of characters of the command which must match - allowing the user to enter only a portion of the keyword as a shortcut. The third and fourth fields are strings giving the command usage and a brief help string. A NULL in the Help field indicates that the corresponding keyword is a synonym for another command its usage/help should not be shown. The final field is a pointer to a function of type CMD_EXEC_FUNC which will be invoked if the parser encounters the corresponding command.The third group of functions provide standard CMD_EXEC_FUNCs for certain commonly used commands, such as CmdParserHelpFunc and CmdParserExitFunc as shown in the preceding example.
The caller may pass a generic (pVOID) parameter to the command line parsing functions in the second group. This function is in turn passed to the CMD_EXEC_FUNCs. In this way, the caller can specify context information for the command execution functions.
Commands are executed after the user presses [enter]. Multiple commands may be entered on the same command line separated by semicolons (;). Each command as if it had been entered on a separate line (unless a command terminates with an error, in which case all remaining commands entered on the same line will be ignored).
PromptAndExecCmd( ) - Prompt for a command and execute it.
UINT16 PromptAndExecCmd ( pVOID param, /* Generic parameter for exec funcs */ char * pPrompt, /* Prompt to display */ FILE * fin, /* Input stream */ FILE * fout, /* Output stream */ CMD_DESCR * pCmdTable /* CMD_DESCR table */ )
Displays pPrompt to fout and prompts for input from fin. Then, parses/executes the command. pCmdTable points to an array of CMD_DESCR structures defining the command to be recognized by the parser, and Param is a generic parameter passed down to individual command execution functions.
RET_OK for normal termination
RET_ERROR for program failure.
RET_CONTINUE if execution should continue.
KeywordMatch( ) - Compare keywords
int KeywordMatch ( char * s1, /* string 1 */ char * s2, /* string 2 */ int len /* max length to compare */ )
Compares s1 and s2 up to len characters, case insensitive. Returns 0 if strings are equal.
This function is equivalent to strnicmp( ), but that function is not available in all libraries.
0 if s1 and s2 are the same
-n if s1 < s2
+n if s1 > s2
ExecCmd( ) - Execute the command line
UINT16 ExecCmd ( pVOID param, /* Generic parameter for exec funcs */ char * pCmd, /* Cmd buffer to be parsed/executed */ FILE * fin, /* Stream for input */ FILE * fout, /* Stream for output */ CMD_DESCR * pCmdTable /* CMD_DESCR table */ )
Parses and executes the commands in the pCmd buffer. I/O - if any - will go to fin/fout. The pCmd may contain any number of commands separated by CMD_SEPARATOR. pCmdTable points to an array of CMD_DESCR structures defining the command to be recognized by the parser, and param is a generic parameter passed down to individual command execution functions.
RET_OK for normal termination.
RET_ERROR for program failure.
RET_CONTINUE if execution should continue.
SkipSpace( ) - Skips leading white space in a string
#define IS_SPACE ( c )
Returns a pointer to the first non-white-space character in pStr.
Ptr to first non-white-space character in pStr
TruncSpace( ) - Truncates string to eliminate trailing whitespace
UINT16 TruncSpace ( char * pStr /* Input string */ )
Trucates pStr to eliminate trailing white space. Returns count of characters left in pStr upon return.
Number of characters in pStr after truncation.
GetNextToken( ) - Retrieves the next token from an input string
char *GetNextToken ( char * pStr, /* Input string */ char * pToken, /* Bfr to receive token */ UINT16 tokenLen /* Max length of Token bfr */ )
Copies the next token from pStr to pToken. White space before the next token is discarded. Tokens are delimited by white space and by the command separator, CMD_SEPARATOR. No more than tokenLen - 1 characters from pStr will be copied into pToken. tokenLen must be at least one and pToken will be NULL terminated upon return.
Pointer into pStr following end of copied pToken.
GetHexToken( ) - Retrieves value of hex token
char *GetHexToken ( char * pStr, /* input string */ long * pToken, /* buffer to receive token value */ long defVal /* default value */ )
Retrieves the next token from pCmd line, interprets it as a hex value, and stores the result in pToken. If there are no remaining tokens, stores defVal in pToken instead.
Pointer into pStr following end of copied pToken
CmdParserHelpFunc( ) - Displays list of supported commands
UINT16 CmdParserHelpFunc ( pVOID param, /* Generic parameter passed down */ char * *ppCmd, /* Ptr to remainder of cmd line */ FILE * fin, /* stream for input (if any) */ FILE * fout /* stream for output (if any) */ )
Displays the list of commands in the parser command table to fout. When the parser recognizes that this function is about to be executed, it substitutes a pointer to the current CMD_DESCR table in param. If this function is called directly, param should point to a table of CMD_DESCR structures.
RET_CONTINUE
CmdParserExitFunc( ) - Terminates parser execution
UINT16 CmdParserExitFunc ( pVOID param, /* Generic parameter passed down */ char * *ppCmd, /* Ptr to remainder of cmd line */ FILE * fin, /* stream for input (if any) */ FILE * fout /* stream for output (if any) */ )
Returns RET_OK, causing the parser to return RET_OK to the caller signally normal termination of the parser.
RET_OK