Shell

Simple shell interpreter. More...

Detailed Description

Simple shell interpreter.

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) More...
#define	SHELL_COMMAND(cmd, help, func)
	Define shell command. More...

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

Functions
void	shell_post_readline_hook (void)
	Optional hook after readline has triggered. More...
void	shell_pre_command_hook (int argc, char **argv)
	Optional hook before shell command is called. More...
void	shell_post_command_hook (int ret, int argc, char **argv)
	Optional hook after shell command is called. More...
void	shell_run_once (const shell_command_t *commands, char *line_buf, int len)
	Start a shell and exit once EOF is reached. More...
static void	shell_run_forever (const shell_command_t *commands, char *line_buf, int len)
	Start a shell and restart it if it exits. More...
static void	shell_run (const shell_command_t *commands, char *line_buf, int len)
	Back-porting alias for shell_run_forever. More...

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

Definition at line 230 of file shell.h.

SHELL_DEFAULT_BUFSIZE

#define SHELL_DEFAULT_BUFSIZE   (128)

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

Definition at line 79 of file shell.h.

Typedef Documentation

shell_command_handler_t

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

Protype of a shell callback handler.

The functions supplied to shell_run() must use this signature. The argument list is terminated with a NULL, i.e argv[argc] == NULL`. argv[0]`` is the function name.

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 can be used by getopt() or a similar function.

Parameters

[in]	argc	Number of arguments supplied to the function invocation.
[in]	argv	The supplied argument list.

Returns

0 on success

Anything else on failure

Definition at line 129 of file shell.h.

shell_command_t

typedef struct shell_command_t 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_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]	ret	Return value of the shell command.
[in]	argc	Number of arguments supplied to the function invocation.
[in]	argv	The 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]	argc	Number of arguments supplied to the function invocation.
[in]	argv	The 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]	commands	ptr to array of command structs
[in]	line_buf	Buffer that will be used for reading a line
[in]	len	nr of bytes that fit in line_buf

Definition at line 194 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]	commands	ptr to array of command structs
[in]	line_buf	Buffer that will be used for reading a line
[in]	len	nr of bytes that fit in line_buf

Definition at line 175 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]	commands	ptr to array of command structs
[in]	line_buf	Buffer that will be used for reading a line
[in]	len	nr of bytes that fit in line_buf