This section provides a reference to the µC/Shell API. Each of the user-accessible services is presented in alphabetical order. The following information is provided for each of those services:
- A brief description
- The function prototype
- The filename of the source code
- A description of the arguments passed to the function
- A description of the returned value(s)
- Specific notes and warnings on using the service
- A usage example
Shell_CmdTblAdd()
| File | Called from |
shell.c | Application |
Allocates and initializes a module command, and inserts a command table into it.
Arguments
cmd_tbl_name
Pointer to character string representing the name of the command table.
cmd_tbl
Command table to add.
perr
Pointer to variable that will receive the return error code from this function :
SHELL_ERR_NONE
No error.
SHELL_ERR_NULL_PTR
Argument 'cmd_tbl' passed a NULL pointer.
SHELL_ERR_MODULE_CMD_EMPTY
Command table empty.
SHELL_ERR_MODULE_CMD_ALREADY_IN
Command table already added, or command table name already used.
SHELL_ERR_MODULE_CMD_NONE_AVAIL
NO available module command to allocate.
SHELL_ERR_MODULE_CMD_NAME_NONE
No module command name found.
SHELL_ERR_MODULE_CMD_NAME_TOO_LONG
Module command name too long.
SHELL_ERR_MODULE_CMD_NAME_COPY
Copy error.
Returned Values
None.
Notes/Warnings
The 'cmd_tbl_ame' argument is the prefix of the commands in 'cmd_tbl'. In order to speed up the command search, the shell first locate the appropriate table based on the prefix of the command. Hence, it is recommended that all commands in a table be named with the same prefix. For instance, µC/TCP-IP related command displaying statistics could look like :
Net_stats
while a file system command listing the current directory would be :
FS_ls
The names of those module commands are respectively 'Net' and 'FS'.
Example
Shell_CmdTblRem ()
| File | Called from |
shell.c | Application |
Removes a command table from the shell.
Arguments
cmd_tbl_name
Pointer to character string representing the name of the command table.
perr
Pointer to variable that will receive the return error code from this function:
SHELL_ERR_NONE
No error.
SHELL_ERR_NULL_PTR
Argument 'cmd_tbl_name' passed a NULL pointer.
SHELL_ERR_MODULE_CMD_NOT_FOUND
Module command NOT found.
Returned Values
None.
Notes/Warnings
None.
Example
Shell_Exec ()
| File | Called from |
shell.c | Application |
Parses and executes the command passed in parameter.
Arguments
in
Pointer to a CPU_CHAR string holding a complete command and its argument(s).
out_fnct
Pointer to 'output' function used by command.
perr
Pointer to variable that will receive the return error code from this function:
SHELL_ERR_NONE
No error.
SHELL_ERR_NULL_PTR
Argument 'in' passed a NULL pointer.
SHELL_ERR_CMD_NOT_FOUND
Command NOT found.
SHELL_ERR_CMD_SEARCH
Error searching for command.
SHELL_ERR_CMD_EXEC
Error executing command.
SHELL_ERR_ARG_TBL_FULL
Argument table full and token still to be parsed.
Returned Values
SHELL_EXEC_ERR
If command executing error.
Command specific return value
Otherwise.
Notes/Warnings
The command may generate some output that should be transmitted to some device (socket, RS-232 link, ...). The caller of this function is hence responsible for the implementation of such function, if output is desired.
Example
Shell_Init()
| File | Called from |
shell.c | Application |
Initializes the shell.
Arguments
None
Returned Values
DEF_OK
Shell initialization successful.
DEF_FAIL
Otherwise.
Notes/Warnings
The Shell_Init() function must be called before the other Shell function are invoked. Shell_Init() must also only be called once from product's application.