source: rtems/cpukit/libmisc/shell/shell.h @ 89fd08e

4.11
Last change on this file since 89fd08e was 89fd08e, checked in by Chris Johns <chrisj@…>, on Aug 14, 2017 at 4:50:55 AM

libmisc/shell: Make some internal shell functions public.

  • Add 'rtems_shell_init_environment()' so a user can create the shell environment without needing to run a shell.
  • Move 'rtems_shell_lookup_topic', 'rtems_shell_can_see_cmd', and 'rtems_shell_execute_cmd' from the internal interface to the public interface.

Closes #3104.

  • Property mode set to 100644
File size: 9.3 KB
Line 
1/**
2 * @file rtems/shell.h
3 *
4 * @brief Instantatiate a New Terminal Shell
5 */
6
7/*
8 *  Author:
9 *
10 *   WORK: fernando.ruiz@ctv.es
11 *   HOME: correo@fernando-ruiz.com
12 *
13 *   Thanks at:
14 *    Chris Johns
15 */
16
17#ifndef __RTEMS_SHELL_H__
18#define __RTEMS_SHELL_H__
19
20#include <sys/types.h>
21#include <sys/stat.h>
22#include <rtems.h>
23#include <stdio.h>
24#include <termios.h>
25#include <rtems/fs.h>
26#include <rtems/libio.h>
27#include <rtems/chain.h>
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33/*
34 * Some key labels to define special keys.
35 */
36
37#define RTEMS_SHELL_KEYS_EXTENDED    (0x8000)
38#define RTEMS_SHELL_KEYS_NORMAL_MASK (0x00ff)
39#define RTEMS_SHELL_KEYS_INS         (0)
40#define RTEMS_SHELL_KEYS_DEL         (1)
41#define RTEMS_SHELL_KEYS_UARROW      (2)
42#define RTEMS_SHELL_KEYS_DARROW      (3)
43#define RTEMS_SHELL_KEYS_LARROW      (4)
44#define RTEMS_SHELL_KEYS_RARROW      (5)
45#define RTEMS_SHELL_KEYS_HOME        (6)
46#define RTEMS_SHELL_KEYS_END         (7)
47#define RTEMS_SHELL_KEYS_F1          (8)
48#define RTEMS_SHELL_KEYS_F2          (9)
49#define RTEMS_SHELL_KEYS_F3          (10)
50#define RTEMS_SHELL_KEYS_F4          (11)
51#define RTEMS_SHELL_KEYS_F5          (12)
52#define RTEMS_SHELL_KEYS_F6          (13)
53#define RTEMS_SHELL_KEYS_F7          (14)
54#define RTEMS_SHELL_KEYS_F8          (15)
55#define RTEMS_SHELL_KEYS_F9          (16)
56#define RTEMS_SHELL_KEYS_F10         (17)
57
58typedef bool (*rtems_shell_login_check_t)(
59  const char * /* user */,
60  const char * /* passphrase */
61);
62
63extern bool rtems_shell_login_prompt(
64  FILE *in,
65  FILE *out,
66  const char *device,
67  rtems_shell_login_check_t check
68);
69
70extern bool rtems_shell_login_check(
71  const char *user,
72  const char *passphrase
73);
74
75typedef int (*rtems_shell_command_t)(int argc, char **argv);
76
77struct rtems_shell_cmd_tt;
78typedef struct rtems_shell_cmd_tt rtems_shell_cmd_t;
79
80struct rtems_shell_cmd_tt {
81  const char            *name;
82  const char            *usage;
83  const char            *topic;
84  rtems_shell_command_t  command;
85  rtems_shell_cmd_t     *alias;
86  rtems_shell_cmd_t     *next;
87  mode_t                 mode;
88  uid_t                  uid;
89  gid_t                  gid;
90};
91
92typedef struct {
93  const char *name;
94  const char *alias;
95} rtems_shell_alias_t;
96
97struct rtems_shell_topic_tt;
98typedef struct rtems_shell_topic_tt rtems_shell_topic_t;
99
100struct rtems_shell_topic_tt {
101  const char          *topic;
102  rtems_shell_topic_t *next;
103};
104
105/*
106 * The return value has RTEMS_SHELL_KEYS_EXTENDED set if the key
107 * is extended, ie a special key.
108 */
109extern unsigned int rtems_shell_getchar(FILE *in);
110
111extern rtems_shell_cmd_t * rtems_shell_lookup_cmd(const char *cmd);
112
113extern rtems_shell_cmd_t *rtems_shell_add_cmd_struct(
114  rtems_shell_cmd_t *shell_cmd
115);
116
117rtems_shell_cmd_t * rtems_shell_add_cmd(
118  const char            *cmd,
119  const char            *topic,
120  const char            *usage,
121  rtems_shell_command_t  command
122);
123
124extern rtems_shell_cmd_t * rtems_shell_alias_cmd(
125  const char *cmd,
126  const char *alias
127);
128
129extern int rtems_shell_make_args(
130  char  *commandLine,
131  int   *argc_p,
132  char **argv_p,
133  int    max_args
134);
135
136extern rtems_shell_topic_t * rtems_shell_lookup_topic(
137  const char *topic
138);
139
140extern bool rtems_shell_can_see_cmd(
141  const rtems_shell_cmd_t *shell_cmd
142);
143
144extern int rtems_shell_execute_cmd(
145  const char *cmd, int argc, char *argv[]
146);
147
148/*
149 * Call to set up the shell environment if you need to execute commands before
150 * running a shell.
151 */
152extern void rtems_shell_init_environment(
153  void
154);
155
156extern int rtems_shell_cat_file(
157  FILE *out,
158  const char *name
159);
160
161extern void rtems_shell_write_file(
162  const char *name,
163  const char *content
164);
165
166extern int rtems_shell_script_file(
167  int    argc,
168  char **argv
169);
170
171/**
172 * Initialise the shell creating tasks to login and run the shell
173 * sessions.
174 *
175 * @param task_name Name of the shell task.
176 * @param task_stacksize The size of the stack. If 0 the default size is used.
177 * @param task_priority The priority the shell runs at.
178 * @param forever Repeat logins.
179 * @param wait Caller should block until shell exits.
180 * @param login_check User login check function, NULL disables login checks.
181 *
182 */
183extern rtems_status_code rtems_shell_init(
184  const char *task_name,
185  size_t task_stacksize,
186  rtems_task_priority task_priority,
187  const char *devname,
188  bool forever,
189  bool wait,
190  rtems_shell_login_check_t login_check
191);
192
193/**
194 * Run a shell script creating a shell tasks to execute the command under.
195 *
196 * @param task_name Name of the shell task.
197 * @param task_stacksize The size of the stack. If 0 the default size is used.
198 * @param task_priority The priority the shell runs at.
199 * @param input The file of commands. Can be 'stdin' to use stdin.
200 * @param output The output file to write commands to. Can be 'stdout',
201 *              'stderr' or '/dev/null'.
202 * @param output_append Append the output to the file or truncate the file.
203 *                      Create if it does not exist.
204 * @param wait Wait for the script to finish.
205 */
206extern rtems_status_code rtems_shell_script(
207  const char          *task_name,
208  size_t               task_stacksize,  /* 0 default*/
209  rtems_task_priority  task_priority,
210  const char          *input,
211  const char          *output,
212  bool                 output_append,
213  bool                 wait,
214  bool                 echo
215);
216
217/**
218 *  Private environment associated with each shell instance.
219 */
220typedef struct {
221  /** 'S','E','N','V': Shell Environment */
222  rtems_name magic;
223  const char *devname;
224  const char *taskname;
225  bool exit_shell; /* logout */
226  bool forever; /* repeat login */
227  int errorlevel;
228  bool echo;
229  char cwd[256];
230  const char *input;
231  const char *output;
232  bool output_append;
233  rtems_id wake_on_end;
234  rtems_shell_login_check_t login_check;
235
236  /**
237   * @brief The real and effective UID of the shell task in case no login check
238   * is present.
239   */
240  uid_t uid;
241
242  /**
243   * @brief The real and effective GID of the shell task in case no login check
244   * is present.
245   */
246  gid_t gid;
247} rtems_shell_env_t;
248
249bool rtems_shell_main_loop(
250  rtems_shell_env_t *rtems_shell_env
251);
252
253extern const rtems_shell_env_t rtems_global_shell_env;
254
255rtems_shell_env_t *rtems_shell_get_current_env(void);
256void rtems_shell_dup_current_env(rtems_shell_env_t *);
257
258/*
259 * The types of file systems we can mount. We have them broken out
260 * out like this so they can be configured by shellconfig.h. The
261 * mount command needs special treatment due to some file systems
262 * being dependent on the network stack and some not. If we had
263 * all possible file systems being included it would force the
264 * networking stack into the applcation and this may not be
265 * required.
266 */
267struct rtems_shell_filesystems_tt;
268typedef struct rtems_shell_filesystems_tt rtems_shell_filesystems_t;
269
270typedef int (*rtems_shell_filesystems_mounter_t)(
271  const char*                driver,
272  const char*                path,
273  rtems_shell_filesystems_t* fs,
274  rtems_filesystem_options_t options
275);
276
277struct rtems_shell_filesystems_tt {
278  rtems_chain_node                         link;
279  const char                              *name;
280  int                                      driver_needed;
281  const rtems_filesystem_operations_table *fs_ops;
282  rtems_shell_filesystems_mounter_t        mounter;
283};
284
285/**
286 *  This method dynamically builds the command line prompt string
287 *  and places it in @a prompt.
288 *
289 *  @param[in] shell_env is the shell execution environment
290 *  @param[in] prompt is a pointer to a string buffer area
291 *  @param[in] size is length of the prompt buffer area
292 *
293 *  @return This method fills in the memory pointed to by @a prompt.
294 *
295 *  @note An application specific implementation can be provided
296 *        by the user.
297 */
298extern void rtems_shell_get_prompt(
299  rtems_shell_env_t *shell_env,
300  char              *prompt,
301  size_t             size
302);
303
304/**
305 * Helper for the mount command.
306 *
307 * @param[in] driver The path to the driver.
308 * @param[in] path The path to mount on.
309 * @param[in] fs The file system definition.
310 * @param[in] options Special file system options.
311 */
312extern int rtems_shell_libc_mounter(
313  const char*                driver,
314  const char*                path,
315  rtems_shell_filesystems_t* fs,
316  rtems_filesystem_options_t options
317);
318
319/**
320 * Add a new file system mount configuration to the mount command.
321 *
322 * @param[in] fs The file system mount data.
323 */
324extern void rtems_shell_mount_add_fsys(rtems_shell_filesystems_t* fs);
325
326/**
327 * Delete file system mount configuration from the mount command.
328 *
329 * @param[in] fs The file system mount data to remove.
330 */
331extern void rtems_shell_mount_del_fsys(rtems_shell_filesystems_t* fs);
332
333typedef void (*rtems_shell_wait_for_input_notification)(
334  int fd,
335  int seconds_remaining,
336  void *arg
337);
338
339/**
340 * @brief Waits for input.
341 *
342 * @retval RTEMS_SUCCESSFUL Input detected.
343 * @retval RTEMS_TIMEOUT Timeout expired.
344 * @retval RTEMS_UNSATISFIED Cannot change or restore termios attributes.
345 */
346extern rtems_status_code rtems_shell_wait_for_input(
347  int fd,
348  int timeout_in_seconds,
349  rtems_shell_wait_for_input_notification notification,
350  void *notification_arg
351);
352
353extern int rtems_shell_main_monitor(int argc, char **argv);
354
355/*
356 * Provide these commands for application use, as their implementation
357 * is tedious.
358 */
359int rtems_shell_main_mv(int argc, char *argv[]);
360int rtems_shell_main_cp(int argc, char *argv[]);
361int rtems_shell_main_rm(int argc, char *argv[]);
362
363#ifdef __cplusplus
364}
365#endif
366
367#endif
Note: See TracBrowser for help on using the repository browser.