FD.io VPP  v18.07-rc0-415-g6c78436
Vector Packet Processing
format.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015 Cisco and/or its affiliates.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at:
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 /*
16  Copyright (c) 2001, 2002, 2003 Eliot Dresselhaus
17 
18  Permission is hereby granted, free of charge, to any person obtaining
19  a copy of this software and associated documentation files (the
20  "Software"), to deal in the Software without restriction, including
21  without limitation the rights to use, copy, modify, merge, publish,
22  distribute, sublicense, and/or sell copies of the Software, and to
23  permit persons to whom the Software is furnished to do so, subject to
24  the following conditions:
25 
26  The above copyright notice and this permission notice shall be
27  included in all copies or substantial portions of the Software.
28 
29  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
30  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
31  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
32  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
33  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
34  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
35  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
36 */
37 
38 #ifndef included_format_h
39 #define included_format_h
40 
41 #include <stdarg.h>
42 
43 #include <vppinfra/clib.h> /* for CLIB_UNIX, etc. */
44 #include <vppinfra/vec.h>
45 #include <vppinfra/error.h> /* for ASSERT */
46 #include <vppinfra/string.h>
47 
48 typedef u8 *(format_function_t) (u8 * s, va_list * args);
49 
50 u8 *va_format (u8 * s, const char *format, va_list * args);
51 u8 *format (u8 * s, const char *format, ...);
52 
53 #ifdef CLIB_UNIX
54 
55 #include <stdio.h>
56 
57 #else /* ! CLIB_UNIX */
58 
59 /* We're not Unix and have not stdio.h */
60 #define FILE void
61 #define stdin ((FILE *) 0)
62 #define stdout ((FILE *) 1)
63 #define stderr ((FILE *) 2)
64 
65 #endif
66 
67 word va_fformat (FILE * f, char *fmt, va_list * va);
68 word fformat (FILE * f, char *fmt, ...);
69 word fdformat (int fd, char *fmt, ...);
70 
73 {
74  u32 indent = 0;
75  u8 *nl;
76 
77  if (!s)
78  return indent;
79 
80  nl = vec_end (s) - 1;
81  while (nl >= s)
82  {
83  if (*nl-- == '\n')
84  break;
85  indent++;
86  }
87  return indent;
88 }
89 
90 #define _(f) u8 * f (u8 * s, va_list * va)
91 
92 /* Standard user-defined formats. */
93 _(format_vec32);
98 _(format_f64);
100 
101 #ifdef CLIB_UNIX
102 /* Unix specific formats. */
109 _(format_sockaddr);
114 _(format_hostname);
115 _(format_timeval);
117 _(format_signal);
119 #endif
120 
121 #undef _
122 
123 /* Unformat. */
124 
125 typedef struct _unformat_input_t
126 {
127  /* Input buffer (vector). */
128  u8 *buffer;
129 
130  /* Current index in input buffer. */
131  uword index;
132 
133  /* Vector of buffer marks. Used to delineate pieces of the buffer
134  for error reporting and for parse recovery. */
135  uword *buffer_marks;
136 
137  /* User's function to fill the buffer when its empty
138  (and argument). */
139  uword (*fill_buffer) (struct _unformat_input_t * i);
140 
141  /* Return values for fill buffer function which indicate whether not
142  input has been exhausted. */
143 #define UNFORMAT_END_OF_INPUT (~0)
144 #define UNFORMAT_MORE_INPUT 0
145 
146  /* User controlled argument to fill buffer function. */
147  void *fill_buffer_arg;
149 
150 always_inline void
152  uword (*fill_buffer) (unformat_input_t *),
153  void *fill_buffer_arg)
154 {
155  memset (i, 0, sizeof (i[0]));
156  i->fill_buffer = fill_buffer;
157  i->fill_buffer_arg = fill_buffer_arg;
158 }
159 
160 always_inline void
162 {
163  vec_free (i->buffer);
164  vec_free (i->buffer_marks);
165  memset (i, 0, sizeof (i[0]));
166 }
167 
170 {
171  /* Low level fill input function. */
172  extern uword _unformat_fill_input (unformat_input_t * i);
173 
174  if (i->index >= vec_len (i->buffer) && i->index != UNFORMAT_END_OF_INPUT)
175  _unformat_fill_input (i);
176 
177  return i->index;
178 }
179 
180 /* Return true if input is exhausted */
183 {
185 }
186 
187 /* Return next element in input vector,
188  possibly calling fill input to get more. */
191 {
192  uword i = unformat_check_input (input);
193  if (i < vec_len (input->buffer))
194  {
195  input->index = i + 1;
196  i = input->buffer[i];
197  }
198  return i;
199 }
200 
201 /* Back up input pointer by one. */
202 always_inline void
204 {
205  input->index -= 1;
206 }
207 
208 /* Peek current input character without advancing. */
211 {
212  uword c = unformat_get_input (input);
213  if (c != UNFORMAT_END_OF_INPUT)
214  unformat_put_input (input);
215  return c;
216 }
217 
218 /* Skip current input line. */
219 always_inline void
221 {
222  uword c;
223 
224  while ((c = unformat_get_input (i)) != UNFORMAT_END_OF_INPUT && c != '\n')
225  ;
226 }
227 
229 
230 /* Unformat function. */
232  va_list * args);
233 
234 /* External functions. */
235 
236 /* General unformatting function with programmable input stream. */
237 uword unformat (unformat_input_t * i, const char *fmt, ...);
238 
239 /* Call user defined parse function.
240  unformat_user (i, f, ...) is equivalent to unformat (i, "%U", f, ...) */
242  ...);
243 
244 /* Alternate version which allows for extensions. */
245 uword va_unformat (unformat_input_t * i, const char *fmt, va_list * args);
246 
247 /* Setup for unformat of Unix style command line. */
248 void unformat_init_command_line (unformat_input_t * input, char *argv[]);
249 
250 /* Setup for unformat of given string. */
252  char *string, int string_len);
253 
254 always_inline void
256 {
257  unformat_init_string (input, string, strlen (string));
258 }
259 
260 /* Setup for unformat of given vector string; vector will be freed by unformat_string. */
261 void unformat_init_vector (unformat_input_t * input, u8 * vector_string);
262 
263 /* Format function for unformat input usable when an unformat error
264  has occurred. */
265 u8 *format_unformat_error (u8 * s, va_list * va);
266 
267 #define unformat_parse_error(input) \
268  clib_error_return (0, "parse error `%U'", format_unformat_error, input)
269 
270 /* Print all input: not just error context. */
271 u8 *format_unformat_input (u8 * s, va_list * va);
272 
273 /* Unformat (parse) function which reads a %s string and converts it
274  to and unformat_input_t. */
276 
277 /* Parse a line ending with \n and return it. */
279 
280 /* Parse a line ending with \n and return it as an unformat_input_t. */
282 
283 /* Parse a token containing given set of characters. */
285 
286 /* Parses a hexstring into a vector of bytes. */
288 
289 /* Returns non-zero match if input is exhausted.
290  Useful to ensure that the entire input matches with no trailing junk. */
292 
293 /* Parse memory size e.g. 100, 100k, 100m, 100g. */
295 
296 /* Unparse memory size e.g. 100, 100k, 100m, 100g. */
297 u8 *format_memory_size (u8 * s, va_list * va);
298 
299 /* Format c identifier: e.g. a_name -> "a name". */
300 u8 *format_c_identifier (u8 * s, va_list * va);
301 
302 /* Format hexdump with both hex and printable chars - compatible with text2pcap */
303 u8 *format_hexdump (u8 * s, va_list * va);
304 
305 /* Unix specific formats. */
306 #ifdef CLIB_UNIX
307 /* Setup input from Unix file. */
308 void unformat_init_clib_file (unformat_input_t * input, int file_descriptor);
309 
310 /* Take input from Unix environment variable; returns
311  1 if variable exists zero otherwise. */
312 uword unformat_init_unix_env (unformat_input_t * input, char *var);
313 
314 /* Unformat unix group id (gid) specified as integer or string */
316 #endif /* CLIB_UNIX */
317 
318 /* Test code. */
319 int test_format_main (unformat_input_t * input);
321 
322 /* This is not the right place for this, but putting it in vec.h
323 created circular dependency problems. */
324 int test_vec_main (unformat_input_t * input);
325 
326 #endif /* included_format_h */
327 
328 /*
329  * fd.io coding-style-patch-verification: ON
330  *
331  * Local Variables:
332  * eval: (c-set-style "gnu")
333  * End:
334  */
uword unformat_init_unix_env(unformat_input_t *input, char *var)
Definition: unformat.c:1066
uword( unformat_function_t)(unformat_input_t *input, va_list *args)
Definition: format.h:231
unformat_function_t unformat_token
Definition: format.h:284
u8 * format_time_float(u8 *s, va_list *args)
Definition: unix-formats.c:835
u8 * format_ascii_bytes(u8 *s, va_list *va)
Definition: std-formats.c:74
unformat_function_t unformat_eof
Definition: format.h:291
static uword unformat_get_input(unformat_input_t *input)
Definition: format.h:190
unformat_function_t unformat_input
Definition: format.h:275
unformat_function_t unformat_hex_string
Definition: format.h:287
u8 * format(u8 *s, const char *format,...)
Definition: format.c:419
unformat_function_t unformat_unix_gid
Definition: format.h:315
int i
u8 * format_ip4_tos_byte(u8 *s, va_list *args)
Definition: unix-formats.c:420
u8 * format_icmp4_type_and_code(u8 *s, va_list *args)
Definition: unix-formats.c:319
uword unformat_user(unformat_input_t *input, unformat_function_t *func,...)
Definition: unformat.c:983
u8 * format_ip4_packet(u8 *s, va_list *args)
Definition: unix-formats.c:450
static u32 format_get_indent(u8 *s)
Definition: format.h:72
u8 *( format_function_t)(u8 *s, va_list *args)
Definition: format.h:48
word va_fformat(FILE *f, char *fmt, va_list *va)
Definition: format.c:429
unsigned char u8
Definition: types.h:56
void unformat_init_clib_file(unformat_input_t *input, int file_descriptor)
Definition: unformat.c:1058
u8 * format_timeval(u8 *s, va_list *args)
Definition: unix-formats.c:761
static void unformat_skip_line(unformat_input_t *i)
Definition: format.h:220
i64 word
Definition: types.h:111
u8 * format_address_family(u8 *s, va_list *va)
Definition: unix-formats.c:93
#define always_inline
Definition: clib.h:92
word fdformat(int fd, char *fmt,...)
Definition: format.c:467
u8 * format_white_space(u8 *s, va_list *va)
Definition: std-formats.c:113
int test_unformat_main(unformat_input_t *input)
u8 * format_memory_size(u8 *s, va_list *va)
Definition: std-formats.c:193
u8 * format_hex_bytes(u8 *s, va_list *va)
Definition: std-formats.c:84
unsigned int u32
Definition: types.h:88
#define vec_end(v)
End (last data address) of vector.
void unformat_init_string(unformat_input_t *input, char *string, int string_len)
Definition: unformat.c:1023
unformat_function_t unformat_line_input
Definition: format.h:281
u8 * format_c_identifier(u8 *s, va_list *va)
Definition: std-formats.c:258
struct _unformat_input_t unformat_input_t
u8 * format_unix_interface_flags(u8 *s, va_list *args)
Definition: unix-formats.c:582
static void unformat_init_cstring(unformat_input_t *input, char *string)
Definition: format.h:255
void unformat_init_command_line(unformat_input_t *input, char *argv[])
Definition: unformat.c:1007
u8 * format_unix_arphrd(u8 *s, va_list *args)
Definition: unix-formats.c:532
static void unformat_put_input(unformat_input_t *input)
Definition: format.h:203
int test_vec_main(unformat_input_t *input)
u8 * format_network_port(u8 *s, va_list *args)
Definition: unix-formats.c:187
u8 * format_sockaddr(u8 *s, va_list *args)
Definition: unix-formats.c:230
void unformat_init_vector(unformat_input_t *input, u8 *vector_string)
Definition: unformat.c:1031
u8 * format_unformat_input(u8 *s, va_list *va)
Definition: unformat.c:143
#define UNFORMAT_END_OF_INPUT
Definition: format.h:143
svmdb_client_t * c
#define vec_free(V)
Free vector&#39;s memory (no header).
Definition: vec.h:339
u8 * format_vec32(u8 *s, va_list *va)
Definition: std-formats.c:43
u8 * format_hexdump(u8 *s, va_list *va)
Definition: std-formats.c:281
static void unformat_init(unformat_input_t *i, uword(*fill_buffer)(unformat_input_t *), void *fill_buffer_arg)
Definition: format.h:151
u8 * format_network_protocol(u8 *s, va_list *args)
Definition: unix-formats.c:169
u8 * format_vec_uword(u8 *s, va_list *va)
Definition: std-formats.c:58
unformat_function_t unformat_line
Definition: format.h:278
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)
u64 uword
Definition: types.h:112
static void unformat_free(unformat_input_t *i)
Definition: format.h:161
u8 * format_signal(u8 *s, va_list *args)
Definition: unix-formats.c:847
u8 * format_time_interval(u8 *s, va_list *args)
Definition: std-formats.c:122
unformat_function_t unformat_memory_size
Definition: format.h:294
u8 * va_format(u8 *s, const char *format, va_list *args)
Definition: format.c:387
u8 * format_unformat_error(u8 *s, va_list *va)
Definition: unformat.c:91
u8 * format_network_address(u8 *s, va_list *args)
Definition: unix-formats.c:206
u8 * format_ethernet_packet(u8 *s, va_list *args)
Definition: unix-formats.c:710
u8 * format_hostname(u8 *s, va_list *args)
Definition: unix-formats.c:750
word fformat(FILE *f, char *fmt,...)
Definition: format.c:453
int test_format_main(unformat_input_t *input)
uword unformat_skip_white_space(unformat_input_t *input)
Definition: unformat.c:815
static uword unformat_peek_input(unformat_input_t *input)
Definition: format.h:210
uword va_unformat(unformat_input_t *i, const char *fmt, va_list *args)
Definition: unformat.c:833
uword unformat(unformat_input_t *i, const char *fmt,...)
Definition: unformat.c:972
static uword unformat_is_eof(unformat_input_t *input)
Definition: format.h:182
u8 * format_ucontext_pc(u8 *s, va_list *args)
Definition: unix-formats.c:898
CLIB vectors are ubiquitous dynamically resized arrays with by user defined "headers".
static uword unformat_check_input(unformat_input_t *i)
Definition: format.h:169