shell.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316
  1. /*
  2. * shell.h
  3. */
  4. /**
  5. \ingroup clish
  6. \defgroup clish_shell shell
  7. @{
  8. \brief This class represents the top level container for a CLI session.
  9. */
  10. #ifndef _clish_shell_h
  11. #define _clish_shell_h
  12. #include <stdio.h>
  13. #include <sys/types.h>
  14. #include <pwd.h>
  15. #include "lub/c_decl.h"
  16. #include "lub/types.h"
  17. #include "lub/argv.h"
  18. #include "tinyrl/tinyrl.h"
  19. #include "clish/view.h"
  20. #include "clish/ptype.h"
  21. #include "clish/var.h"
  22. #include "clish/plugin.h"
  23. #include "konf/net.h"
  24. #define CLISH_LOCK_PATH "/tmp/clish.lock"
  25. #define CLISH_LOCK_WAIT 20
  26. typedef struct clish_shell_s clish_shell_t;
  27. /* This is used to hold context during callbacks */
  28. struct clish_context_s {
  29. clish_shell_t *shell;
  30. const clish_command_t *cmd;
  31. clish_pargv_t *pargv;
  32. const clish_action_t *action;
  33. };
  34. typedef struct clish_context_s clish_context_t;
  35. typedef enum {
  36. SHELL_STATE_OK = 0,
  37. SHELL_STATE_UNKNOWN = 1,
  38. SHELL_STATE_IO_ERROR = 2,
  39. SHELL_STATE_SCRIPT_ERROR = 3,/* Script execution error */
  40. SHELL_STATE_SYNTAX_ERROR = 4, /* Illegal line entered */
  41. SHELL_STATE_SYSTEM_ERROR = 5, /* Some internal system error */
  42. SHELL_STATE_INITIALISING = 6,
  43. SHELL_STATE_HELPING = 7,
  44. SHELL_STATE_EOF = 8, /* EOF of input stream */
  45. SHELL_STATE_CLOSING = 9
  46. } clish_shell_state_t;
  47. typedef enum {
  48. SHELL_VAR_NONE, /* Nothing to escape */
  49. SHELL_VAR_ACTION, /* Variable expanding for ACTION script */
  50. SHELL_VAR_REGEX /* Variable expanding for regex usage */
  51. } clish_shell_var_t;
  52. _BEGIN_C_DECL
  53. /*=====================================
  54. * SHELL INTERFACE
  55. *===================================== */
  56. /**
  57. * A hook function used during the spawning of a new shell.
  58. *
  59. * This will be invoked from the context of the spawned shell's thread
  60. * and will be invoked just after the shell instance is created.
  61. *
  62. * This enables the client-specific initialisation of the spawned shell's
  63. * thread
  64. * e.g. to map the I/O streams, authenticate a user.
  65. *
  66. * N.B. It is possible for a client to have this invoked multiple times
  67. * if the user is spawning new shells using a commmand which uses the
  68. * "clish_spawn" builtin function. Hence the client should remember the
  69. * shell which first calls this function, and only assign resource (e.g.
  70. * setting up a script interpreter) for that call.
  71. *
  72. * \return
  73. * - BOOL_TRUE if everything is OK
  74. * - BOOL_FALSE if the shell should be immediately shut down.
  75. *
  76. */
  77. typedef bool_t clish_shell_init_fn_t(
  78. /**
  79. * The shell instance which invoked this call
  80. */
  81. const clish_shell_t * shell);
  82. /**
  83. * A hook function used during the shutting down of a spawned shell
  84. *
  85. * This will be invoked from the context of the spawned shell's thread
  86. * and will be invoked just before the shell is destroyed.
  87. *
  88. * This enables the client-specific finalisation to occur.
  89. * e.g. releasing any resource held by the cookie,
  90. * shutting down telnet connections
  91. *
  92. * NB. This function may be called multiple times if a user is spawning
  93. * new commands (via the "clish_spawn" builtin command), hence should use
  94. * the reference to the root shell (remembered by the first call to clish_shell_init_fn_t callback)
  95. * to signal when the cleanup should occur.
  96. */
  97. typedef void clish_shell_fini_fn_t(
  98. /**
  99. * The shell instance which invoked this call
  100. */
  101. const clish_shell_t * shell);
  102. /**
  103. * A hook function used to indicate a command line has been executed and the
  104. * shell is about to prompt for the next command.
  105. *
  106. * This will be invoked from the context of the spawned shell's thread
  107. * and will be called once an ACTION has been performed.
  108. *
  109. * A client may use this as a periodic indicator of CLI activity,
  110. * e.g. to manage session timeouts. In addition any required logging of
  111. * commands may be performed.
  112. */
  113. typedef void clish_shell_cmd_line_fn_t(
  114. /**
  115. * The shell instance which invoked this call
  116. */
  117. clish_context_t *context,
  118. /**
  119. * The text of the command line entered
  120. */
  121. const char *cmd_line);
  122. /**
  123. * A hook function used to control config file write
  124. *
  125. */
  126. typedef bool_t clish_shell_config_fn_t(
  127. clish_context_t *context);
  128. /**
  129. * A hook function used to control access for the current user.
  130. *
  131. * This will be invoked from the context of the spawned shell's thread
  132. * and will be called during the parsing of the XML files.
  133. *
  134. * The clish component will only insert a command into a view if the access
  135. * call is sucessfull.
  136. *
  137. * The client may choose to implement invocation of the script in a number of
  138. * ways, which may include forking a sub-process or thread. It is important
  139. * that the call doesn't return until the script has been fully evaluated.
  140. *
  141. * \return
  142. * - BOOL_TRUE - if the user of the current CLISH session is permitted access
  143. * - BOOL_FALSE - if the user of the current CLISH session is not permitted access
  144. *
  145. * \post
  146. * - If access is granted then the associated command will be inserted into the
  147. * appropriate view.
  148. */
  149. typedef bool_t clish_shell_access_fn_t(
  150. /**
  151. * The shell instance which invoked this call
  152. */
  153. const clish_shell_t * instance,
  154. /**
  155. * A textual string which describes a limitation for a command. This
  156. * string typically may be the name of a user group, of which the
  157. * current user must be a member to grant access to a command.
  158. */
  159. const char *access);
  160. typedef int clish_shell_log_fn_t(
  161. clish_context_t *context,
  162. const char *line, int retcode);
  163. /**
  164. * A client of libclish will provide hooks for the control of the CLI within
  165. * a particular system.
  166. * They will populate an instance of this structure and pass it into the
  167. */
  168. typedef struct {
  169. clish_shell_init_fn_t *init_fn; /* Initialisation call */
  170. clish_shell_access_fn_t *access_fn; /* Access control call */
  171. clish_shell_cmd_line_fn_t *cmd_line_fn; /* Command line logging call */
  172. clish_shell_fini_fn_t *fini_fn; /* Finalization call */
  173. clish_shell_config_fn_t *config_fn; /* Config call */
  174. clish_shell_log_fn_t *log_fn; /* Logging call */
  175. } clish_shell_hooks_t;
  176. /*-----------------
  177. * meta functions
  178. *----------------- */
  179. clish_shell_t *clish_shell_new(const clish_shell_hooks_t * hooks,
  180. void *cookie,
  181. FILE * istream,
  182. FILE * ostream,
  183. bool_t stop_on_error);
  184. /*-----------------
  185. * methods
  186. *----------------- */
  187. /*
  188. * Called to invoke the startup command for this shell
  189. */
  190. int clish_shell_startup(clish_shell_t * instance);
  191. void clish_shell_delete(clish_shell_t * instance);
  192. clish_view_t *clish_shell_find_create_view(clish_shell_t * instance,
  193. const char *name,
  194. const char *prompt);
  195. clish_ptype_t *clish_shell_find_create_ptype(clish_shell_t * instance,
  196. const char *name,
  197. const char *text,
  198. const char *pattern,
  199. clish_ptype_method_e method,
  200. clish_ptype_preprocess_e preprocess);
  201. clish_ptype_t *clish_shell_find_ptype(clish_shell_t *instance,
  202. const char *name);
  203. int clish_shell_xml_read(clish_shell_t * instance, const char *filename);
  204. void clish_shell_help(clish_shell_t * instance, const char *line);
  205. int clish_shell_exec_action(clish_context_t *context, char **out);
  206. int clish_shell_execute(clish_context_t *context, char **out);
  207. int clish_shell_forceline(clish_shell_t *instance, const char *line, char ** out);
  208. int clish_shell_readline(clish_shell_t *instance, char ** out);
  209. void clish_shell_dump(clish_shell_t * instance);
  210. void clish_shell_close(clish_shell_t * instance);
  211. /**
  212. * Push the specified file handle on to the stack of file handles
  213. * for this shell. The specified file will become the source of
  214. * commands, until it is exhausted.
  215. *
  216. * \return
  217. * BOOL_TRUE - the file was successfully associated with the shell.
  218. * BOOL_FALSE - there was insufficient resource to associate this file.
  219. */
  220. int clish_shell_push_file(clish_shell_t * instance, const char * fname,
  221. bool_t stop_on_error);
  222. int clish_shell_push_fd(clish_shell_t * instance, FILE * file,
  223. bool_t stop_on_error);
  224. void clish_shell_insert_var(clish_shell_t *instance, clish_var_t *var);
  225. clish_var_t *clish_shell_find_var(clish_shell_t *instance, const char *name);
  226. char *clish_shell_expand_var(const char *name, clish_context_t *context);
  227. char *clish_shell_expand(const char *str, clish_shell_var_t vtype, clish_context_t *context);
  228. /*-----------------
  229. * attributes
  230. *----------------- */
  231. clish_view_t *clish_shell__get_view(const clish_shell_t * instance);
  232. unsigned clish_shell__get_depth(const clish_shell_t * instance);
  233. const char *clish_shell__get_viewid(const clish_shell_t * instance);
  234. const char *clish_shell__get_overview(const clish_shell_t * instance);
  235. tinyrl_t *clish_shell__get_tinyrl(const clish_shell_t * instance);
  236. void *clish_shell__get_client_cookie(const clish_shell_t * instance);
  237. void
  238. clish_shell__set_pwd(clish_shell_t *instance, const char * line,
  239. clish_view_t * view, char * viewid, clish_context_t *context);
  240. char *clish_shell__get_pwd_line(const clish_shell_t * instance,
  241. unsigned int index);
  242. char *clish_shell__get_pwd_full(const clish_shell_t * instance, unsigned depth);
  243. clish_view_t *clish_shell__get_pwd_view(const clish_shell_t * instance,
  244. unsigned int index);
  245. konf_client_t *clish_shell__get_client(const clish_shell_t * instance);
  246. FILE *clish_shell__get_istream(const clish_shell_t * instance);
  247. FILE *clish_shell__get_ostream(const clish_shell_t * instance);
  248. void clish_shell__set_lockfile(clish_shell_t * instance, const char * path);
  249. char * clish_shell__get_lockfile(clish_shell_t * instance);
  250. int clish_shell__set_socket(clish_shell_t * instance, const char * path);
  251. int clish_shell_load_scheme(clish_shell_t * instance, const char * xml_path);
  252. int clish_shell_loop(clish_shell_t * instance);
  253. clish_shell_state_t clish_shell__get_state(const clish_shell_t * instance);
  254. void clish_shell__set_state(clish_shell_t * instance,
  255. clish_shell_state_t state);
  256. void clish_shell__set_startup_view(clish_shell_t * instance, const char * viewname);
  257. void clish_shell__set_startup_viewid(clish_shell_t * instance, const char * viewid);
  258. void clish_shell__set_default_shebang(clish_shell_t * instance, const char * shebang);
  259. const char * clish_shell__get_default_shebang(const clish_shell_t * instance);
  260. const char * clish_shell__get_fifo(clish_shell_t * instance);
  261. void clish_shell__set_interactive(clish_shell_t * instance, bool_t interactive);
  262. bool_t clish_shell__get_interactive(const clish_shell_t * instance);
  263. bool_t clish_shell__get_utf8(const clish_shell_t * instance);
  264. void clish_shell__set_utf8(clish_shell_t * instance, bool_t utf8);
  265. void clish_shell__set_timeout(clish_shell_t *instance, int timeout);
  266. char *clish_shell__get_line(clish_context_t *context);
  267. char *clish_shell__get_full_line(clish_context_t *context);
  268. char *clish_shell__get_params(clish_context_t *context);
  269. void clish_shell__set_log(clish_shell_t *instance, bool_t log);
  270. bool_t clish_shell__get_log(const clish_shell_t *instance);
  271. int clish_shell_wdog(clish_shell_t *instance);
  272. void clish_shell__set_wdog_timeout(clish_shell_t *instance,
  273. unsigned int timeout);
  274. unsigned int clish_shell__get_wdog_timeout(const clish_shell_t *instance);
  275. int clish_shell__save_history(const clish_shell_t *instance, const char *fname);
  276. int clish_shell__restore_history(clish_shell_t *instance, const char *fname);
  277. void clish_shell__stifle_history(clish_shell_t *instance, unsigned int stifle);
  278. struct passwd *clish_shell__get_user(clish_shell_t *instance);
  279. void clish_shell__set_dryrun(clish_shell_t *instance, bool_t dryrun);
  280. bool_t clish_shell__get_dryrun(const clish_shell_t *instance);
  281. /* Plugin functions */
  282. int clish_shell_load_plugins(clish_shell_t *instance);
  283. int clish_shell_link_plugins(clish_shell_t *instance);
  284. /* Unresolved symbols functions */
  285. clish_sym_t *clish_shell_find_sym(clish_shell_t *instance,
  286. const char *name, int type);
  287. clish_sym_t *clish_shell_add_sym(clish_shell_t *instance,
  288. clish_plugin_fn_t *func, const char *name, int type);
  289. clish_sym_t *clish_shell_add_unresolved_sym(clish_shell_t *instance,
  290. const char *name, int type);
  291. _END_C_DECL
  292. #endif /* _clish_shell_h */
  293. /** @} clish_shell */