mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
2c1a2863ce
This change is in preparation to [PR 10788]. PR 10788 will make the shell exitable which may lead to unexpected behavior in comparison to previous usage of the shell. To prevent this, this PR introduces two "new" functions to the shell's API: `shell_run_once()` and `shell_run_forever()`. `shell_run_once()` basically has the same behavior as `shell_run()` in current master: Start a shell and continue reading lines until EOF is reached. `shell_run_forever()` wraps around `shell_run_once()` and restarts the shell if it exits. `shell_run()` is re-introduced as a back-porting alias for `shell_run_forever()`. As a consequence all current calls to `shell_run()` won't exit even with [PR 10788] merged (which would add EOT as additional exit condition for `shell_run_once()`). [PR 10788]: https://github.com/RIOT-OS/RIOT/pull/10788
109 lines
3.3 KiB
C
109 lines
3.3 KiB
C
/*
|
|
* Copyright (C) 2009-2013 Freie Universität Berlin
|
|
*
|
|
* This file is subject to the terms and conditions of the GNU Lesser
|
|
* General Public License v2.1. See the file LICENSE in the top level
|
|
* directory for more details.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup sys_shell Shell
|
|
* @ingroup sys
|
|
* @brief Simple shell interpreter
|
|
*
|
|
* @{
|
|
*
|
|
* @file
|
|
* @brief Shell interface definition
|
|
*/
|
|
|
|
#ifndef SHELL_H
|
|
#define SHELL_H
|
|
|
|
#include <stdint.h>
|
|
|
|
#include "kernel_defines.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Default shell buffer size (maximum line length shell can handle)
|
|
*/
|
|
#define SHELL_DEFAULT_BUFSIZE (128)
|
|
|
|
/**
|
|
* @brief Protype of a shell callback handler.
|
|
* @details 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.
|
|
* @param[in] argc Number of arguments supplied to the function invocation.
|
|
* @param[in] argv The supplied argument list.
|
|
*
|
|
* @return 0 on success
|
|
* @return Anything else on failure
|
|
*/
|
|
typedef int (*shell_command_handler_t)(int argc, char **argv);
|
|
|
|
/**
|
|
* @brief A single command in the list of the supported commands.
|
|
* @details The list of commands is NULL terminated,
|
|
* i.e. the last element must be ``{ NULL, NULL, NULL }``.
|
|
*/
|
|
typedef struct shell_command_t {
|
|
const char *name; /**< Name of the function */
|
|
const char *desc; /**< Description to print in the "help" command. */
|
|
shell_command_handler_t handler; /**< The callback function. */
|
|
} shell_command_t;
|
|
|
|
/**
|
|
* @brief Start a shell and exit once EOF is reached.
|
|
*
|
|
* @param[in] commands ptr to array of command structs
|
|
* @param[in] line_buf Buffer that will be used for reading a line
|
|
* @param[in] len nr of bytes that fit in line_buf
|
|
*/
|
|
void shell_run_once(const shell_command_t *commands, char *line_buf, int len);
|
|
|
|
/**
|
|
* @brief Start a shell and restart it if it exits
|
|
*
|
|
* @param[in] commands ptr to array of command structs
|
|
* @param[in] line_buf Buffer that will be used for reading a line
|
|
* @param[in] len nr of bytes that fit in line_buf
|
|
*/
|
|
static inline void shell_run_forever(const shell_command_t *commands,
|
|
char *line_buf, int len)
|
|
{
|
|
while (1) {
|
|
shell_run_once(commands, line_buf, len);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @brief Back-porting alias for @ref shell_run_forever
|
|
*
|
|
* @param[in] commands ptr to array of command structs
|
|
* @param[in] line_buf Buffer that will be used for reading a line
|
|
* @param[in] len nr of bytes that fit in line_buf
|
|
*/
|
|
static inline void shell_run(const shell_command_t *commands,
|
|
char *line_buf, int len)
|
|
{
|
|
shell_run_forever(commands, line_buf, len);
|
|
}
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* SHELL_H */
|
|
/** @} */
|