Loading...
Searching...
No Matches
Shell

Simple shell interpreter. More...

Detailed Description

Simple shell interpreter.

Security expectations

Access to the shell grants access to the system that may exercise any power the firmware can exercise. While some commands only provide limited access to the system, and it is best practice for commands to validate their input, there is no expectation of security of the system when an attacker gains access to the shell.

Modules

 Shell commands
 
 Shell compile time configurations
 

Files

file  shell.h
 Shell interface definition.
 

Data Structures

struct  shell_command_t
 A single command in the list of the supported commands. More...
 
struct  shell_command_xfa_t
 A single command in the list of the supported commands. More...
 

Macros

#define SHELL_DEFAULT_BUFSIZE   (128)
 Default shell buffer size (maximum line length shell can handle)
 
#define SHELL_COMMAND(cmd, help, func)
 Define shell command.
 

Typedefs

typedef int(* shell_command_handler_t) (int argc, char **argv)
 Prototype of a shell callback handler.
 
typedef struct shell_command_t shell_command_t
 A single command in the list of the supported commands.
 

Functions

void shell_post_readline_hook (void)
 Optional hook after readline has triggered.
 
void shell_pre_command_hook (int argc, char **argv)
 Optional hook before shell command is called.
 
void shell_post_command_hook (int ret, int argc, char **argv)
 Optional hook after shell command is called.
 
void shell_run_once (const shell_command_t *commands, char *line_buf, int len)
 Start a shell and exit once EOF is reached.
 
static void shell_run_forever (const shell_command_t *commands, char *line_buf, int len)
 Start a shell and restart it if it exits.
 
static void shell_run (const shell_command_t *commands, char *line_buf, int len)
 Back-porting alias for shell_run_forever.
 
int shell_handle_input_line (const shell_command_t *commands, char *line)
 Parse and run a line of text as a shell command with arguments.
 
int shell_parse_file (const shell_command_t *commands, const char *filename, unsigned *line_nr)
 Read shell commands from a file and run them.
 

Macro Definition Documentation

◆ SHELL_COMMAND

#define SHELL_COMMAND (   cmd,
  help,
  func 
)
Value:
XFA_USE_CONST(shell_command_xfa_t*, shell_commands_xfa); \
static FLASH_ATTR const char _xfa_ ## cmd ## _cmd_name[] = #cmd; \
static FLASH_ATTR const char _xfa_ ## cmd ## _cmd_desc[] = help; \
static const shell_command_xfa_t _xfa_ ## cmd ## _cmd = { \
.name = _xfa_ ## cmd ## _cmd_name, \
.desc = _xfa_ ## cmd ## _cmd_desc, \
.handler = &func \
}; \
XFA_ADD_PTR(shell_commands_xfa, cmd, cmd, &_xfa_ ## cmd ## _cmd)
#define FLASH_ATTR
C type qualifier required to place a variable in flash.
Definition flash_utils.h:68
A single command in the list of the supported commands.
Definition shell.h:176
FLASH_ATTR const char * name
Name of the function.
Definition shell.h:177
#define XFA_USE_CONST(type, name)
Declare an external read-only cross-file array.
Definition xfa.h:114

Define shell command.

Note
This is not available from C++, but a trivial C file can easily hook up a extern "C" function implemented in C++.

This macro is a helper for defining a shell command and adding it to the shell commands XFA (cross file array).

Shell commands added using this macros will be sorted after builtins and commands passed via parameter to shell_run_once(). If a command with the same name exists in any of those, they will make a command added via this macro inaccassible.

Commands added with this macro will be sorted alphanumerically by name.

Warning
This feature is experimental!
This should be considered experimental API, subject to change without notice!

Example:

#include "shell.h"
static int _my_command(int argc, char **argv) {
// ...
}
SHELL_COMMAND(my_command, "my command help text", _my_command);
#define SHELL_COMMAND(cmd, help, func)
Define shell command.
Definition shell.h:285
Shell interface definition.

Definition at line 285 of file shell.h.

◆ SHELL_DEFAULT_BUFSIZE

#define SHELL_DEFAULT_BUFSIZE   (128)

Default shell buffer size (maximum line length shell can handle)

Warning
When terminals that buffer input and send the full command line in one go are used on stdin implementations with fast bursts of data, it may be necessary to increase the STDIO_RX_BUFSIZE to make practical use of this buffer, especially because the current mechanism of passing stdin (isrpipe_t stdin_isrpipe) does not support backpressure and overflows silently. As a consequence, commands through such terminals appear to be truncated at STDIO_RX_BUFSIZE bytes (defaulting to 64) unless the command is sent in parts (on many terminals, by pressing Ctrl-D half way through the command).

For example, this affects systems with direct USB stdio (STDIO over CDC ACM (usbus)) with the default terminal pyterm.

Definition at line 100 of file shell.h.

Typedef Documentation

◆ shell_command_handler_t

typedef int(* shell_command_handler_t) (int argc, char **argv)

Prototype of a shell callback handler.

The functions supplied to shell_run() must use this signature. It is designed to mimic the function signature of main(). For this reason, the argument list is terminated with a NULL, i.e argv[argc] == NULL (which is an ANSI-C requirement, and a detail that newlib's getopt() implementation relies on). The function name is passed in argv[0].

Escape sequences are removed before the function is called.

The called function may edit argv and the contained strings, but it must be taken care of not to leave the boundaries of the array. This functionality is another property that many getopt() implementations rely on to provide their so-called "permute" feature extension.

Parameters
[in]argcNumber of arguments supplied to the function invocation.
[in]argvThe supplied argument list.
Returns
0 on success
Anything else on failure

Definition at line 157 of file shell.h.

◆ shell_command_t

A single command in the list of the supported commands.

The list of commands is NULL terminated, i.e. the last element must be { NULL, NULL, NULL }.

Function Documentation

◆ shell_handle_input_line()

int shell_handle_input_line ( const shell_command_t commands,
char *  line 
)

Parse and run a line of text as a shell command with arguments.

Parameters
[in]commandsptr to array of command structs
[in]lineThe input line to parse
Returns
return value of the found command
-ENOEXEC if no valid command could be found

◆ shell_parse_file()

int shell_parse_file ( const shell_command_t commands,
const char *  filename,
unsigned *  line_nr 
)

Read shell commands from a file and run them.

Note
This requires the vfs module.
Parameters
[in]commandsptr to array of command structs
[in]filenamefile to read shell commands from
[out]line_nrline on which an error occurred, may be NULL
Returns
0 if all commands were executed successful error return of failed command otherwise

◆ shell_post_command_hook()

void shell_post_command_hook ( int  ret,
int  argc,
char **  argv 
)

Optional hook after shell command is called.

User implemented function gets called before a valid shell command will be called.

Note
Only executed with the shell_hooks module.
Parameters
[in]retReturn value of the shell command.
[in]argcNumber of arguments supplied to the function invocation.
[in]argvThe supplied argument list.

◆ shell_post_readline_hook()

void shell_post_readline_hook ( void  )

Optional hook after readline has triggered.

User implemented function gets called after the shell readline is complete.

Note
Only executed with the shell_hooks module.

◆ shell_pre_command_hook()

void shell_pre_command_hook ( int  argc,
char **  argv 
)

Optional hook before shell command is called.

User implemented function gets called before a valid shell command will be called.

Note
Only executed with the shell_hooks module.
Parameters
[in]argcNumber of arguments supplied to the function invocation.
[in]argvThe supplied argument list.

◆ shell_run()

static void shell_run ( const shell_command_t commands,
char *  line_buf,
int  len 
)
inlinestatic

Back-porting alias for shell_run_forever.

Parameters
[in]commandsptr to array of command structs
[in]line_bufBuffer that will be used for reading a line
[in]lennr of bytes that fit in line_buf

Definition at line 222 of file shell.h.

◆ shell_run_forever()

static void shell_run_forever ( const shell_command_t commands,
char *  line_buf,
int  len 
)
inlinestatic

Start a shell and restart it if it exits.

             If `CONFIG_SHELL_SHUTDOWN_ON_EXIT` is set (e.g. on native)
             the shell will instead shut down RIOT once EOF is reached.
Parameters
[in]commandsptr to array of command structs
[in]line_bufBuffer that will be used for reading a line
[in]lennr of bytes that fit in line_buf

Definition at line 203 of file shell.h.

◆ shell_run_once()

void shell_run_once ( const shell_command_t commands,
char *  line_buf,
int  len 
)

Start a shell and exit once EOF is reached.

Parameters
[in]commandsptr to array of command structs
[in]line_bufBuffer that will be used for reading a line
[in]lennr of bytes that fit in line_buf