lib, vtysh: Fix memory leaks, change cmd_element to const

Fix a few memory issues:

* Not freeing tab-completions upon input match failure
* Invalid write when null-terminating tab-completions
* Not freeing argv[] itself in additinon to elements
* Use XFREE() instead of free() as appropriate
* Not freeing final token of an [option] during parsing

Make a few minor changes to CLI internals:

* Improve documentation on matching & completion functions
* Only make one copy of cmd_token's when building argv,
  instead of three
* Don't make a copy of the matching cmd_element

Make one major(ish) change to CLI internals:

* Change all pointers to struct cmd_element to const

Code outside of the core CLI units should never have an
occasion to modify the internal state of the command system.
Doing so could easily amount to having a CLI interface that
changes during runtime, and could conceivably lead to security
issues. Explicitly disallowing this removes any chance of
confusion.

Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>

1 files changed, 22 insertions, 5 deletions

diff --git a/lib/command_match.h b/lib/command_match.h
index ac4e70c31..9e18b8d90 100644
--- a/lib/command_match.h
+++ b/lib/command_match.h
@@ -70,23 +70,40 @@ enum match_type
  *
  * @param[in] cmdgraph command graph to match against
  * @param[in] vline vectorized input string
- * @param[out] argv pointer to argument list if successful match
- * @param[out] element pointer to matched cmd_element if successful match
+ * @param[out] argv pointer to argument list if successful match, NULL
+ * otherwise. The elements of this list are pointers to struct cmd_token
+ * and represent the sequence of tokens matched by the inpu. The ->arg
+ * field of each token points to a copy of the input matched on it. These
+ * may be safely deleted or modified.
+ * @param[out] element pointer to matched cmd_element if successful match,
+ * or NULL when MATCHER_ERROR(rv) is true. The cmd_element may *not* be
+ * safely deleted or modified; it is the instance initialized on startup.
  * @return matcher status
  */
 enum matcher_rv
 command_match (struct graph *cmdgraph,
                vector vline,
                struct list **argv,
-               struct cmd_element **element);
+               const struct cmd_element **element);
 
 /**
  * Compiles possible completions for a given line of user input.
  *
  * @param[in] start the start node of the DFA to match against
  * @param[in] vline vectorized input string
- * @param[in] completions pointer to list of cmd_token representing
- *            acceptable next inputs
+ * @param[out] completions pointer to list of cmd_token representing
+ * acceptable next inputs, or NULL when MATCHER_ERROR(rv) is true.
+ * The elements of this list are pointers to struct cmd_token and take on a
+ * variety of forms depending on the passed vline. If the last element in vline
+ * is NULL, all previous elements are considered to be complete words (the case
+ * when a space is the last token of the line) and completions are generated
+ * based on what could follow that input. If the last element in vline is not
+ * NULL and each sequential element matches the corresponding tokens of one or
+ * more commands exactly (e.g. 'encapv4' and not 'en') the same result is
+ * generated. If the last element is not NULL and the best possible match is a
+ * partial match, then the result generated will be all possible continuations
+ * of that element (e.g. 'encapv4', 'encapv6', etc for input 'en').
+ * @return matcher status
  */
 enum matcher_rv
 command_complete (struct graph *cmdgraph,