lib/cmd/include/ucg_cmd.h

   1 /*
   2  * Copyright (c) 2009-2015, Olivier MATZ <zer0@droids-corp.org>
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of the University of California, Berkeley nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 /*-
  29  * Copyright (c) <2010>, Intel Corporation
  30  * All rights reserved.
  31  *
  32  * Redistribution and use in source and binary forms, with or without
  33  * modification, are permitted provided that the following conditions
  34  * are met:
  35  *
  36  * - Redistributions of source code must retain the above copyright
  37  *   notice, this list of conditions and the following disclaimer.
  38  *
  39  * - Redistributions in binary form must reproduce the above copyright
  40  *   notice, this list of conditions and the following disclaimer in
  41  *   the documentation and/or other materials provided with the
  42  *   distribution.
  43  *
  44  * - Neither the name of Intel Corporation nor the names of its
  45  *   contributors may be used to endorse or promote products derived
  46  *   from this software without specific prior written permission.
  47  *
  48  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  49  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  50  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  51  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  52  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  53  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  54  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  55  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  56  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  57  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  58  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  59  * OF THE POSSIBILITY OF SUCH DAMAGE.
  60  */
  61
  62 #ifndef UCG_CMD_H_
  63 #define UCG_CMD_H_
  64
  65 #include <stdarg.h>
  66 #include <stdio.h>
  67 #ifdef UCG_CMD_HAVE_TERMIOS
  68 #include <termios.h>
  69 #endif
  70
  71 #include "ucg_cmd_parse.h"
  72 #include "ucg_cmd_rdline.h"
  73
  74 /**
  75  * A command line structure.
  76  */
  77 struct ucg_cmd {
  78         ucg_cmd_ctx_t *ctx;      /**< The list of commands for this context. */
  79         struct ucg_rdline rdl;   /**< The associated rdline structure. */
  80         char prompt[UCG_RDLINE_PROMPT_SIZE];  /**< The command line prompt. */
  81 #ifdef UCG_CMD_HAVE_TERMIOS
  82         struct termios oldterm;  /**< The old termios info */
  83 #endif
  84         void *opaque;            /**< A user opaque pointer. */
  85 };
  86
  87 /**
  88  * Allocate and initialize a new command line structure
  89  *
  90  * Allocate and initialize a new command line structure, using the
  91  * specified context, prompt and input/output streams.
  92  *
  93  * Once unused, the command line structure should be freed using
  94  * ucg_cmd_free().
  95  *
  96  * @param ctx
  97  *   The command line context.
  98  * @param prompt
  99  *   The command line prompt. The string is copied in the ucg_cmd
 100  *   structure. The prompt must be smaller than UCG_RDLINE_PROMPT_SIZE.
 101  * @param f_in
 102  *   The input stream.
 103  * @param f_out
 104  *   The output stream.
 105  * @return
 106  *   The newly allocated command line structure.
 107  */
 108 struct ucg_cmd *ucg_cmd_new(ucg_cmd_ctx_t *ctx,
 109         const char *prompt, FILE *f_in, FILE *f_out);
 110
 111 /**
 112  * Initialize a new command line structure
 113  *
 114  * Initialize a command line structure, using the specified prompt and
 115  * specified input/output streams.
 116  *
 117  * @param cl
 118  *   The uninitialize command line structure
 119  * @param ctx
 120  *   The command line context
 121  * @param prompt
 122  *   The command line prompt. The string is copied in the ucg_cmd
 123  *   structure. The prompt must be smaller than UCG_RDLINE_PROMPT_SIZE.
 124  * @param f_in
 125  *   The input stream
 126  * @param f_out
 127  *   The output stream
 128  */
 129 void ucg_cmd_init(struct ucg_cmd *cl, ucg_cmd_ctx_t *ctx,
 130         const char *prompt, FILE *f_in, FILE *f_out);
 131
 132 /**
 133  * Set the prompt of the given command line.
 134  */
 135 void ucg_cmd_set_prompt(struct ucg_cmd *cl, const char *prompt);
 136
 137 /**
 138  * Free a previously allocated command line
 139  *
 140  * The structure pointed by cl is freed. The streams f_in and f_out are
 141  * closed, except if it's stdin, stdout, or stderr. Note: the user
 142  * should call ucg_cmd_quit() before calling this function.
 143  *
 144  * @param cl
 145  *   The command line pointer.
 146  */
 147 void ucg_cmd_free(struct ucg_cmd *cl);
 148
 149 /**
 150  * Parse a file use the given cmd context
 151  *
 152  * The output file descriptor (used for instance by cmd_printf) is
 153  * given as a parameter. It can be -1 if no output is required.
 154  */
 155 struct ucg_cmd *ucg_cmd_file_new(ucg_cmd_ctx_t *ctx,
 156         const char *prompt, const char *path, FILE *f_out);
 157
 158 /**
 159  * Print data on the output of the command line
 160  *
 161  * This function is a wrapper to rdline_printf().
 162  *
 163  * @param cl
 164  *   The command line pointer.
 165  * @param fmt
 166  *   The format string, followed by variable arguments.
 167  * @return
 168  *   On success, return the number of characters printed (not including
 169  *   the trailing '\0'). On error, a negative value is returned.
 170  */
 171 int ucg_cmd_printf(struct ucg_cmd *cl, const char *fmt, ...);
 172
 173 /**
 174  * Push an input buffer to the command line.
 175  *
 176  * Typically, this function is called by ucg_cmd_interact() to send the
 177  * input characters to the command line process. It can also be called
 178  * by a user, for instance when new data is received from an input
 179  * socket.
 180  *
 181  * @param cl
 182  *   The command line pointer.
 183  * @param buf
 184  *   The address of the input buffer.
 185  * @param size
 186  *   The len of the input buffer.
 187  * @return
 188  *   The function returns the number of processed characters, or a
 189  *   negative value on error (ex: EOF reached or command line exited).
 190  */
 191 int ucg_cmd_in(struct ucg_cmd *cl, const char *buf, int size);
 192
 193 /* flags for ucg_cmd_interact */
 194 #define UCG_CMD_F_IGNORE_EOF 0x0001   /**< ignore eof when polling */
 195
 196 /**
 197  * Start command line on configured file descriptor. This function
 198  * loops until the user explicitelly call ucg_cmd_quit(), or if the
 199  * input fd reaches EOF.
 200  *
 201  * @param cl
 202  *   The command line pointer
 203  * @param flags
 204  *   Any flags from UCG_CMD_F_*
 205  *   - UCG_CMD_F_IGNORE_EOF: on eof, clear error and continue polling
 206  */
 207 void ucg_cmd_interact(struct ucg_cmd *cl, unsigned flags);
 208
 209 /**
 210  * Stop a running command line.
 211  *
 212  * Actually it will call ucg_rdline_quit() on the associated rdline.
 213  *
 214  * @param cl
 215  *   The command line pointer.
 216  */
 217 void ucg_cmd_quit(struct ucg_cmd *cl);
 218
 219 #endif /* UCG_CMD_H_ */