FD.io VPP  v19.04.2-12-g66b1689
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 _(format_page_map);
120 #endif
121 
122 #undef _
123 
124 /* Unformat. */
125 
126 typedef struct _unformat_input_t
127 {
128  /* Input buffer (vector). */
129  u8 *buffer;
130 
131  /* Current index in input buffer. */
132  uword index;
133 
134  /* Vector of buffer marks. Used to delineate pieces of the buffer
135  for error reporting and for parse recovery. */
136  uword *buffer_marks;
137 
138  /* User's function to fill the buffer when its empty
139  (and argument). */
140  uword (*fill_buffer) (struct _unformat_input_t * i);
141 
142  /* Return values for fill buffer function which indicate whether not
143  input has been exhausted. */
144 #define UNFORMAT_END_OF_INPUT (~0)
145 #define UNFORMAT_MORE_INPUT 0
146 
147  /* User controlled argument to fill buffer function. */
148  void *fill_buffer_arg;
150 
151 always_inline void
153  uword (*fill_buffer) (unformat_input_t *),
154  void *fill_buffer_arg)
155 {
156  clib_memset (i, 0, sizeof (i[0]));
157  i->fill_buffer = fill_buffer;
158  i->fill_buffer_arg = fill_buffer_arg;
159 }
160 
161 always_inline void
163 {
164  vec_free (i->buffer);
165  vec_free (i->buffer_marks);
166  clib_memset (i, 0, sizeof (i[0]));
167 }
168 
171 {
172  /* Low level fill input function. */
173  extern uword _unformat_fill_input (unformat_input_t * i);
174 
175  if (i->index >= vec_len (i->buffer) && i->index != UNFORMAT_END_OF_INPUT)
176  _unformat_fill_input (i);
177 
178  return i->index;
179 }
180 
181 /* Return true if input is exhausted */
184 {
186 }
187 
188 /* Return next element in input vector,
189  possibly calling fill input to get more. */
192 {
193  uword i = unformat_check_input (input);
194  if (i < vec_len (input->buffer))
195  {
196  input->index = i + 1;
197  i = input->buffer[i];
198  }
199  return i;
200 }
201 
202 /* Back up input pointer by one. */
203 always_inline void
205 {
206  input->index -= 1;
207 }
208 
209 /* Peek current input character without advancing. */
212 {
213  uword c = unformat_get_input (input);
214  if (c != UNFORMAT_END_OF_INPUT)
215  unformat_put_input (input);
216  return c;
217 }
218 
219 /* Skip current input line. */
220 always_inline void
222 {
223  uword c;
224 
225  while ((c = unformat_get_input (i)) != UNFORMAT_END_OF_INPUT && c != '\n')
226  ;
227 }
228 
230 
231 /* Unformat function. */
233  va_list * args);
234 
235 /* External functions. */
236 
237 /* General unformatting function with programmable input stream. */
238 uword unformat (unformat_input_t * i, const char *fmt, ...);
239 
240 /* Call user defined parse function.
241  unformat_user (i, f, ...) is equivalent to unformat (i, "%U", f, ...) */
243  ...);
244 
245 /* Alternate version which allows for extensions. */
246 uword va_unformat (unformat_input_t * i, const char *fmt, va_list * args);
247 
248 /* Setup for unformat of Unix style command line. */
249 void unformat_init_command_line (unformat_input_t * input, char *argv[]);
250 
251 /* Setup for unformat of given string. */
253  char *string, int string_len);
254 
255 always_inline void
257 {
258  unformat_init_string (input, string, strlen (string));
259 }
260 
261 /* Setup for unformat of given vector string; vector will be freed by unformat_string. */
262 void unformat_init_vector (unformat_input_t * input, u8 * vector_string);
263 
264 /* Format function for unformat input usable when an unformat error
265  has occurred. */
266 u8 *format_unformat_error (u8 * s, va_list * va);
267 
268 #define unformat_parse_error(input) \
269  clib_error_return (0, "parse error `%U'", format_unformat_error, input)
270 
271 /* Print all input: not just error context. */
272 u8 *format_unformat_input (u8 * s, va_list * va);
273 
274 /* Unformat (parse) function which reads a %s string and converts it
275  to and unformat_input_t. */
277 
278 /* Parse a line ending with \n and return it. */
280 
281 /* Parse a line ending with \n and return it as an unformat_input_t. */
283 
284 /* Parse a token containing given set of characters. */
286 
287 /* Parses a hexstring into a vector of bytes. */
289 
290 /* Returns non-zero match if input is exhausted.
291  Useful to ensure that the entire input matches with no trailing junk. */
293 
294 /* Parse memory size e.g. 100, 100k, 100m, 100g. */
296 
297 /* Unparse memory size e.g. 100, 100k, 100m, 100g. */
298 u8 *format_memory_size (u8 * s, va_list * va);
299 
300 /* Format c identifier: e.g. a_name -> "a name". */
301 u8 *format_c_identifier (u8 * s, va_list * va);
302 
303 /* Format hexdump with both hex and printable chars - compatible with text2pcap */
304 u8 *format_hexdump (u8 * s, va_list * va);
305 
306 /* Unix specific formats. */
307 #ifdef CLIB_UNIX
308 /* Setup input from Unix file. */
309 void unformat_init_clib_file (unformat_input_t * input, int file_descriptor);
310 
311 /* Take input from Unix environment variable; returns
312  1 if variable exists zero otherwise. */
313 uword unformat_init_unix_env (unformat_input_t * input, char *var);
314 
315 /* Unformat unix group id (gid) specified as integer or string */
317 #endif /* CLIB_UNIX */
318 
319 /* Test code. */
320 int test_format_main (unformat_input_t * input);
322 
323 /* This is not the right place for this, but putting it in vec.h
324 created circular dependency problems. */
325 int test_vec_main (unformat_input_t * input);
326 
327 #endif /* included_format_h */
328 
329 /*
330  * fd.io coding-style-patch-verification: ON
331  *
332  * Local Variables:
333  * eval: (c-set-style "gnu")
334  * End:
335  */
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:232
unformat_function_t unformat_token
Definition: format.h:285
u8 * format_time_float(u8 *s, va_list *args)
Definition: unix-formats.c:846
u8 * format_ascii_bytes(u8 *s, va_list *va)
Definition: std-formats.c:74
unformat_function_t unformat_eof
Definition: format.h:292
static uword unformat_get_input(unformat_input_t *input)
Definition: format.h:191
Optimized string handling code, including c11-compliant "safe C library" variants.
unformat_function_t unformat_input
Definition: format.h:276
unformat_function_t unformat_hex_string
Definition: format.h:288
u8 * format(u8 *s, const char *format,...)
Definition: format.c:424
unformat_function_t unformat_unix_gid
Definition: format.h:316
int i
u8 * format_ip4_tos_byte(u8 *s, va_list *args)
Definition: unix-formats.c:430
u8 * format_icmp4_type_and_code(u8 *s, va_list *args)
Definition: unix-formats.c:329
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:460
static u32 format_get_indent(u8 *s)
Definition: format.h:72
clib_memset(h->entries, 0, sizeof(h->entries[0])*entries)
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:438
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:771
static void unformat_skip_line(unformat_input_t *i)
Definition: format.h:221
i64 word
Definition: types.h:111
u8 * format_address_family(u8 *s, va_list *va)
Definition: unix-formats.c:102
#define always_inline
Definition: clib.h:98
word fdformat(int fd, char *fmt,...)
Definition: format.c:487
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_page_map(u8 *s, va_list *args)
Definition: unix-formats.c:969
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:282
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:592
static void unformat_init_cstring(unformat_input_t *input, char *string)
Definition: format.h:256
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:542
static void unformat_put_input(unformat_input_t *input)
Definition: format.h:204
int test_vec_main(unformat_input_t *input)
u8 * format_network_port(u8 *s, va_list *args)
Definition: unix-formats.c:196
u8 * format_sockaddr(u8 *s, va_list *args)
Definition: unix-formats.c:239
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:144
svmdb_client_t * c
#define vec_free(V)
Free vector&#39;s memory (no header).
Definition: vec.h:341
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:152
u8 * format_network_protocol(u8 *s, va_list *args)
Definition: unix-formats.c:178
u8 * format_vec_uword(u8 *s, va_list *va)
Definition: std-formats.c:58
unformat_function_t unformat_line
Definition: format.h:279
#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:162
u8 * format_signal(u8 *s, va_list *args)
Definition: unix-formats.c:858
u8 * format_time_interval(u8 *s, va_list *args)
Definition: std-formats.c:122
unformat_function_t unformat_memory_size
Definition: format.h:295
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:215
u8 * format_ethernet_packet(u8 *s, va_list *args)
Definition: unix-formats.c:720
u8 * format_hostname(u8 *s, va_list *args)
Definition: unix-formats.c:760
word fformat(FILE *f, char *fmt,...)
Definition: format.c:462
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:211
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:183
u8 * format_ucontext_pc(u8 *s, va_list *args)
Definition: unix-formats.c:909
CLIB vectors are ubiquitous dynamically resized arrays with by user defined "headers".
static uword unformat_check_input(unformat_input_t *i)
Definition: format.h:170