FD.io VPP  v21.10.1-2-g0a485f517
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) __clib_export 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. */
108 _(format_sockaddr);
109 _(format_timeval);
111 _(format_signal);
113 #endif
114 
115 #undef _
116 
117 /* Unformat. */
118 
119 typedef struct _unformat_input_t
120 {
121  /* Input buffer (vector). */
122  u8 *buffer;
123 
124  /* Current index in input buffer. */
125  uword index;
126 
127  /* Vector of buffer marks. Used to delineate pieces of the buffer
128  for error reporting and for parse recovery. */
129  uword *buffer_marks;
130 
131  /* User's function to fill the buffer when its empty
132  (and argument). */
133  uword (*fill_buffer) (struct _unformat_input_t * i);
134 
135  /* Return values for fill buffer function which indicate whether not
136  input has been exhausted. */
137 #define UNFORMAT_END_OF_INPUT (~0)
138 #define UNFORMAT_MORE_INPUT 0
139 
140  /* User controlled argument to fill buffer function. */
141  void *fill_buffer_arg;
143 
144 always_inline void
146  uword (*fill_buffer) (unformat_input_t *),
147  void *fill_buffer_arg)
148 {
149  clib_memset (i, 0, sizeof (i[0]));
150  i->fill_buffer = fill_buffer;
151  i->fill_buffer_arg = fill_buffer_arg;
152 }
153 
154 always_inline void
156 {
157  vec_free (i->buffer);
158  vec_free (i->buffer_marks);
159  clib_memset (i, 0, sizeof (i[0]));
160 }
161 
164 {
165  /* Low level fill input function. */
166  extern uword _unformat_fill_input (unformat_input_t * i);
167 
168  if (i->index >= vec_len (i->buffer) && i->index != UNFORMAT_END_OF_INPUT)
169  _unformat_fill_input (i);
170 
171  return i->index;
172 }
173 
174 /* Return true if input is exhausted */
177 {
179 }
180 
181 /* Return next element in input vector,
182  possibly calling fill input to get more. */
185 {
186  uword i = unformat_check_input (input);
187  if (i < vec_len (input->buffer))
188  {
189  input->index = i + 1;
190  i = input->buffer[i];
191  }
192  return i;
193 }
194 
195 /* Back up input pointer by one. */
196 always_inline void
198 {
199  input->index -= 1;
200 }
201 
202 /* Peek current input character without advancing. */
205 {
206  uword c = unformat_get_input (input);
207  if (c != UNFORMAT_END_OF_INPUT)
208  unformat_put_input (input);
209  return c;
210 }
211 
212 /* Skip current input line. */
213 always_inline void
215 {
216  uword c;
217 
218  while ((c = unformat_get_input (i)) != UNFORMAT_END_OF_INPUT && c != '\n')
219  ;
220 }
221 
223 
224 /* Unformat function. */
226  va_list * args);
227 
228 /* External functions. */
229 
230 /* General unformatting function with programmable input stream. */
231 uword unformat (unformat_input_t * i, const char *fmt, ...);
232 
233 /* Call user defined parse function.
234  unformat_user (i, f, ...) is equivalent to unformat (i, "%U", f, ...) */
236  ...);
237 
238 /* Alternate version which allows for extensions. */
239 uword va_unformat (unformat_input_t * i, const char *fmt, va_list * args);
240 
241 /* Setup for unformat of Unix style command line. */
242 void unformat_init_command_line (unformat_input_t * input, char *argv[]);
243 
244 /* Setup for unformat of given string. */
246  char *string, int string_len);
247 
248 always_inline void
250 {
251  unformat_init_string (input, string, strlen (string));
252 }
253 
254 /* Setup for unformat of given vector string; vector will be freed by unformat_string. */
255 void unformat_init_vector (unformat_input_t * input, u8 * vector_string);
256 
257 /* Format function for unformat input usable when an unformat error
258  has occurred. */
259 u8 *format_unformat_error (u8 * s, va_list * va);
260 
261 #define unformat_parse_error(input) \
262  clib_error_return (0, "parse error `%U'", format_unformat_error, input)
263 
264 /* Print all input: not just error context. */
265 u8 *format_unformat_input (u8 * s, va_list * va);
266 
267 /* Unformat (parse) function which reads a %s string and converts it
268  to and unformat_input_t. */
270 
271 /* Parse a line ending with \n and return it. */
273 
274 /* Parse a line ending with \n and return it as an unformat_input_t. */
276 
277 /* Parse a token containing given set of characters. */
279 
280 /* Parses a hexstring into a vector of bytes. */
282 
283 /* Returns non-zero match if input is exhausted.
284  Useful to ensure that the entire input matches with no trailing junk. */
286 
287 /* Parse memory size e.g. 100, 100k, 100m, 100g. */
289 
290 /* Unparse memory size e.g. 100, 100k, 100m, 100g. */
291 u8 *format_memory_size (u8 * s, va_list * va);
292 
293 /* Parse memory page size e.g. 4K, 2M */
295 
296 /* Unparse memory page size e.g. 4K, 2M */
297 u8 *format_log2_page_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 uword unformat_data_size (unformat_input_t * input, va_list * args);
319 
320 /* Test code. */
321 int test_format_main (unformat_input_t * input);
323 
324 /* This is not the right place for this, but putting it in vec.h
325 created circular dependency problems. */
326 int test_vec_main (unformat_input_t * input);
327 
328 #endif /* included_format_h */
329 
330 /*
331  * fd.io coding-style-patch-verification: ON
332  *
333  * Local Variables:
334  * eval: (c-set-style "gnu")
335  * End:
336  */
format_unformat_input
u8 * format_unformat_input(u8 *s, va_list *va)
Definition: unformat.c:143
unformat_init_clib_file
void unformat_init_clib_file(unformat_input_t *input, int file_descriptor)
Definition: unformat.c:1064
format_timeval
u8 * format_timeval(u8 *s, va_list *args)
Definition: unix-formats.c:288
unformat_user
uword unformat_user(unformat_input_t *input, unformat_function_t *func,...)
Definition: unformat.c:989
unformat_init_vector
void unformat_init_vector(unformat_input_t *input, u8 *vector_string)
Definition: unformat.c:1037
buffer
char * buffer
Definition: cJSON.h:163
format_signal
u8 * format_signal(u8 *s, va_list *args)
Definition: unix-formats.c:375
f
vlib_frame_t * f
Definition: interface_output.c:1098
unformat_line_input
unformat_function_t unformat_line_input
Definition: format.h:275
clib.h
string.h
format_hex_bytes
u8 * format_hex_bytes(u8 *s, va_list *va)
Definition: std-formats.c:84
vec_end
#define vec_end(v)
End (last data address) of vector.
Definition: vec_bootstrap.h:197
va_format
u8 * va_format(u8 *s, const char *format, va_list *args)
Definition: format.c:391
format_network_address
u8 * format_network_address(u8 *s, va_list *args)
Definition: unix-formats.c:212
format_hexdump
u8 * format_hexdump(u8 *s, va_list *va)
Definition: std-formats.c:352
unformat_input_t
struct _unformat_input_t unformat_input_t
unformat_token
unformat_function_t unformat_token
Definition: format.h:278
format_log2_page_size
u8 * format_log2_page_size(u8 *s, va_list *va)
Definition: std-formats.c:273
format_ucontext_pc
u8 * format_ucontext_pc(u8 *s, va_list *args)
Definition: unix-formats.c:426
format_hex_bytes_no_wrap
u8 * format_hex_bytes_no_wrap(u8 *s, va_list *va)
Definition: std-formats.c:112
unformat
uword unformat(unformat_input_t *i, const char *fmt,...)
Definition: unformat.c:978
unformat_init_cstring
static void unformat_init_cstring(unformat_input_t *input, char *string)
Definition: format.h:249
unformat_eof
unformat_function_t unformat_eof
Definition: format.h:285
unformat_put_input
static void unformat_put_input(unformat_input_t *input)
Definition: format.h:197
unformat_init_unix_env
uword unformat_init_unix_env(unformat_input_t *input, char *var)
Definition: unformat.c:1072
unformat_memory_size
unformat_function_t unformat_memory_size
Definition: format.h:288
unformat_peek_input
static uword unformat_peek_input(unformat_input_t *input)
Definition: format.h:204
vec_len
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)
Definition: vec_bootstrap.h:142
unformat_free
static void unformat_free(unformat_input_t *i)
Definition: format.h:155
error.h
unformat_skip_white_space
uword unformat_skip_white_space(unformat_input_t *input)
Definition: unformat.c:821
test_format_main
int test_format_main(unformat_input_t *input)
unformat_check_input
static uword unformat_check_input(unformat_input_t *i)
Definition: format.h:163
c
svmdb_client_t * c
Definition: vpp_get_metrics.c:48
uword
u64 uword
Definition: types.h:112
va_unformat
uword va_unformat(unformat_input_t *i, const char *fmt, va_list *args)
Definition: unformat.c:839
fformat
word fformat(FILE *f, char *fmt,...)
Definition: format.c:466
format_time_interval
u8 * format_time_interval(u8 *s, va_list *args)
Definition: std-formats.c:138
format_unformat_error
u8 * format_unformat_error(u8 *s, va_list *va)
Definition: unformat.c:91
unformat_get_input
static uword unformat_get_input(unformat_input_t *input)
Definition: format.h:184
fmt
int cJSON_bool fmt
Definition: cJSON.h:160
format_memory_size
u8 * format_memory_size(u8 *s, va_list *va)
Definition: std-formats.c:209
format_address_family
u8 * format_address_family(u8 *s, va_list *va)
Definition: unix-formats.c:99
unformat_hex_string
unformat_function_t unformat_hex_string
Definition: format.h:281
format_function_t
u8 *() format_function_t(u8 *s, va_list *args)
Definition: format.h:48
unformat_unix_gid
unformat_function_t unformat_unix_gid
Definition: format.h:315
vec_free
#define vec_free(V)
Free vector's memory (no header).
Definition: vec.h:395
index
u32 index
Definition: flow_types.api:221
always_inline
#define always_inline
Definition: rdma_mlx5dv.h:23
format
u8 * format(u8 *s, const char *format,...)
Definition: format.c:428
unformat_init_string
void unformat_init_string(unformat_input_t *input, char *string, int string_len)
Definition: unformat.c:1029
format_c_identifier
u8 * format_c_identifier(u8 *s, va_list *va)
Definition: std-formats.c:329
format_get_indent
static u32 format_get_indent(u8 *s)
Definition: format.h:72
fdformat
word fdformat(int fd, char *fmt,...)
Definition: format.c:491
u32
unsigned int u32
Definition: types.h:88
va_fformat
word va_fformat(FILE *f, char *fmt, va_list *va)
Definition: format.c:442
unformat_skip_line
static void unformat_skip_line(unformat_input_t *i)
Definition: format.h:214
unformat_data_size
uword unformat_data_size(unformat_input_t *input, va_list *args)
Definition: unformat.c:1081
test_vec_main
int test_vec_main(unformat_input_t *input)
unformat_function_t
uword() unformat_function_t(unformat_input_t *input, va_list *args)
Definition: format.h:225
vec.h
format_time_float
u8 * format_time_float(u8 *s, va_list *args)
Definition: unix-formats.c:363
clib_memset
clib_memset(h->entries, 0, sizeof(h->entries[0]) *entries)
format_vec32
u8 * format_vec32(u8 *s, va_list *va)
Definition: std-formats.c:43
u8
unsigned char u8
Definition: types.h:56
i
int i
Definition: flowhash_template.h:376
unformat_log2_page_size
unformat_function_t unformat_log2_page_size
Definition: format.h:294
unformat_is_eof
static uword unformat_is_eof(unformat_input_t *input)
Definition: format.h:176
unformat_init_command_line
void unformat_init_command_line(unformat_input_t *input, char *argv[])
Definition: unformat.c:1013
word
i64 word
Definition: types.h:111
format_vec_uword
u8 * format_vec_uword(u8 *s, va_list *va)
Definition: std-formats.c:58
format_network_port
u8 * format_network_port(u8 *s, va_list *args)
Definition: unix-formats.c:193
test_unformat_main
int test_unformat_main(unformat_input_t *input)
format_sockaddr
u8 * format_sockaddr(u8 *s, va_list *args)
Definition: unix-formats.c:236
unformat_line
unformat_function_t unformat_line
Definition: format.h:272
format_ascii_bytes
u8 * format_ascii_bytes(u8 *s, va_list *va)
Definition: std-formats.c:74
format_network_protocol
u8 * format_network_protocol(u8 *s, va_list *args)
Definition: unix-formats.c:175
unformat_init
static void unformat_init(unformat_input_t *i, uword(*fill_buffer)(unformat_input_t *), void *fill_buffer_arg)
Definition: format.h:145
format_white_space
u8 * format_white_space(u8 *s, va_list *va)
Definition: std-formats.c:129
unformat_input
unformat_function_t unformat_input
Definition: format.h:269
UNFORMAT_END_OF_INPUT
#define UNFORMAT_END_OF_INPUT
Definition: format.h:137