Shell

Interactive console shell and command registry. More...

Collaboration diagram for Shell:

Typedefs
typedef session_t	shell_context_t
	Command execution context: the session the command runs in.
typedef int(*	shell_command_handler_t) (shell_context_t *context, int argc, char **argv)
	Command handler.

Functions
void	shell_init (void)
	Register the built-in commands.
void	shell_register_command (const char *name, const char *help, shell_command_handler_t handler)
	Add a command.
int	shell_read_line (char *buffer, size_t max_length)
	Read and echo one console line.
int	shell_execute_line (shell_context_t *context, char *line)
	Tokenize and run one command line in a session.
void	shell_run (void)
	Run the interactive shell.

Detailed Description

Interactive console shell and command registry.

The shell runs in the foreground on the standard streams. Built-in commands live in src/subsystems/shell/builtin/. The shell and extending guides listed under Guides describe the commands and how to add one.

Typedef Documentation

shell_command_handler_t

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

Command handler.

During the call, context is the current session, so libc path operations resolve against its working directory.

Parameters

context	Session running the command.
argc	Number of arguments, including the command name.
argv	Arguments; argv[argc] is NULL. The strings point into the input line and are valid only during the call.

Returns

Exit status stored in the session's last_status; 0 for success.

Function Documentation

shell_init()

void shell_init

(

void

)

Register the built-in commands.

Does nothing if any command is already registered. Call it before registering other commands, or the built-ins are never added.

shell_register_command()

void shell_register_command	(	const char *	name,
		const char *	help,
		shell_command_handler_t	handler
	)

Add a command.

The strings are retained by pointer and must outlive the shell. Each registration allocates a list entry from the heap. On allocation failure or a NULL argument, the command is silently not registered. A later registration with the same name hides the earlier one, and help lists the newest commands first.

Parameters

name	Command name matched against the first input token.
help	One-line description shown by help, including usage.
handler	Function run for the command.

shell_read_line()

int shell_read_line	(	char *	buffer,
		size_t	max_length
	)

Read and echo one console line.

Accepts CR, LF, or CRLF as one line ending. Handles backspace and delete, clears the screen on Ctrl-L, rings the bell when the buffer is full, and ignores other control characters.

Parameters

[out]	buffer	Destination for the NUL-terminated line.
	max_length	Capacity of buffer, including the terminator.

Returns

Line length without the terminator; -1 for invalid arguments or end of file; -2 for Ctrl-C, Ctrl-D, or Ctrl-Z, which empties buffer.

shell_execute_line()

int shell_execute_line	(	shell_context_t *	context,
		char *	line
	)

Tokenize and run one command line in a session.

Splits line on spaces and tabs in place; there is no quoting or escaping. Makes context the current session while the command runs, then restores the previous one.

Parameters

context	Session that runs the command. Its user must not be NULL.
line	Writable NUL-terminated input. It is modified.

Returns

The command's status; 2 for more than CONFIG_HOMECORE_SHELL_MAX_ARGS arguments; 127 for an unknown command; the previous status for an empty line. Each of these is stored in last_status. Returns -1 without changing the session if an argument or context->user is NULL.

shell_run()

void shell_run

(

void

)

Run the interactive shell.

Does not return.

Repeatedly prints the prompt for the current session, reads a line with shell_read_line(), and runs it with shell_execute_line().