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