blob: d143ecdb6e9e24370884b98a59f93a55e33b013b [file] [log] [blame]
Ed Warnickecb9cada2015-12-08 15:45:58 -07001/*
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
Dave Barachc3799992016-08-15 11:12:27 -040043#include <vppinfra/clib.h> /* for CLIB_UNIX, etc. */
Ed Warnickecb9cada2015-12-08 15:45:58 -070044#include <vppinfra/vec.h>
Dave Barachc3799992016-08-15 11:12:27 -040045#include <vppinfra/error.h> /* for ASSERT */
Ed Warnickecb9cada2015-12-08 15:45:58 -070046#include <vppinfra/string.h>
47
Dave Barachc3799992016-08-15 11:12:27 -040048typedef u8 *(format_function_t) (u8 * s, va_list * args);
Ed Warnickecb9cada2015-12-08 15:45:58 -070049
Neale Ranns0bfe5d82016-08-25 15:29:12 +010050u8 *va_format (u8 * s, const char *format, va_list * args);
51u8 *format (u8 * s, const char *format, ...);
Ed Warnickecb9cada2015-12-08 15:45:58 -070052
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
Dave Barachc3799992016-08-15 11:12:27 -040067word va_fformat (FILE * f, char *fmt, va_list * va);
68word fformat (FILE * f, char *fmt, ...);
69word fdformat (int fd, char *fmt, ...);
Ed Warnickecb9cada2015-12-08 15:45:58 -070070
Christophe Fontained3c008d2017-10-02 18:10:54 +020071always_inline u32
Ed Warnickecb9cada2015-12-08 15:45:58 -070072format_get_indent (u8 * s)
73{
Christophe Fontained3c008d2017-10-02 18:10:54 +020074 u32 indent = 0;
Dave Barachc3799992016-08-15 11:12:27 -040075 u8 *nl;
Ed Warnickecb9cada2015-12-08 15:45:58 -070076
Dave Barachc3799992016-08-15 11:12:27 -040077 if (!s)
Ed Warnickecb9cada2015-12-08 15:45:58 -070078 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
Damjan Mariondae1c7e2020-10-17 13:32:25 +020090#define _(f) __clib_export u8 * f (u8 * s, va_list * va)
Ed Warnickecb9cada2015-12-08 15:45:58 -070091
92/* Standard user-defined formats. */
Dave Barachc3799992016-08-15 11:12:27 -040093_(format_vec32);
94_(format_vec_uword);
95_(format_ascii_bytes);
96_(format_hex_bytes);
Damjan Marion3860a772019-06-17 23:20:27 +020097_(format_hex_bytes_no_wrap);
Dave Barachc3799992016-08-15 11:12:27 -040098_(format_white_space);
99_(format_f64);
100_(format_time_interval);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700101
102#ifdef CLIB_UNIX
103/* Unix specific formats. */
Dave Barachc3799992016-08-15 11:12:27 -0400104_(format_address_family);
Dave Barachc3799992016-08-15 11:12:27 -0400105_(format_network_address);
106_(format_network_protocol);
107_(format_network_port);
108_(format_sockaddr);
Dave Barachc3799992016-08-15 11:12:27 -0400109_(format_timeval);
110_(format_time_float);
111_(format_signal);
112_(format_ucontext_pc);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700113#endif
114
115#undef _
116
117/* Unformat. */
118
Dave Barachc3799992016-08-15 11:12:27 -0400119typedef struct _unformat_input_t
120{
Ed Warnickecb9cada2015-12-08 15:45:58 -0700121 /* Input buffer (vector). */
Dave Barachc3799992016-08-15 11:12:27 -0400122 u8 *buffer;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700123
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. */
Dave Barachc3799992016-08-15 11:12:27 -0400129 uword *buffer_marks;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700130
131 /* User's function to fill the buffer when its empty
132 (and argument). */
Dave Barachc3799992016-08-15 11:12:27 -0400133 uword (*fill_buffer) (struct _unformat_input_t * i);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700134
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. */
Dave Barachc3799992016-08-15 11:12:27 -0400141 void *fill_buffer_arg;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700142} unformat_input_t;
143
144always_inline void
145unformat_init (unformat_input_t * i,
Dave Barachc3799992016-08-15 11:12:27 -0400146 uword (*fill_buffer) (unformat_input_t *),
147 void *fill_buffer_arg)
Ed Warnickecb9cada2015-12-08 15:45:58 -0700148{
Dave Barachb7b92992018-10-17 10:38:51 -0400149 clib_memset (i, 0, sizeof (i[0]));
Ed Warnickecb9cada2015-12-08 15:45:58 -0700150 i->fill_buffer = fill_buffer;
151 i->fill_buffer_arg = fill_buffer_arg;
152}
153
154always_inline void
155unformat_free (unformat_input_t * i)
156{
157 vec_free (i->buffer);
158 vec_free (i->buffer_marks);
Dave Barachb7b92992018-10-17 10:38:51 -0400159 clib_memset (i, 0, sizeof (i[0]));
Ed Warnickecb9cada2015-12-08 15:45:58 -0700160}
161
162always_inline uword
163unformat_check_input (unformat_input_t * i)
164{
165 /* Low level fill input function. */
166 extern uword _unformat_fill_input (unformat_input_t * i);
167
Dave Barachc3799992016-08-15 11:12:27 -0400168 if (i->index >= vec_len (i->buffer) && i->index != UNFORMAT_END_OF_INPUT)
Ed Warnickecb9cada2015-12-08 15:45:58 -0700169 _unformat_fill_input (i);
170
171 return i->index;
172}
173
174/* Return true if input is exhausted */
175always_inline uword
176unformat_is_eof (unformat_input_t * input)
177{
178 return unformat_check_input (input) == UNFORMAT_END_OF_INPUT;
179}
180
181/* Return next element in input vector,
182 possibly calling fill input to get more. */
183always_inline uword
184unformat_get_input (unformat_input_t * input)
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. */
196always_inline void
197unformat_put_input (unformat_input_t * input)
Dave Barachc3799992016-08-15 11:12:27 -0400198{
199 input->index -= 1;
200}
Ed Warnickecb9cada2015-12-08 15:45:58 -0700201
202/* Peek current input character without advancing. */
203always_inline uword
204unformat_peek_input (unformat_input_t * input)
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. */
Dave Barachc3799992016-08-15 11:12:27 -0400213always_inline void
214unformat_skip_line (unformat_input_t * i)
Ed Warnickecb9cada2015-12-08 15:45:58 -0700215{
216 uword c;
217
Dave Barachc3799992016-08-15 11:12:27 -0400218 while ((c = unformat_get_input (i)) != UNFORMAT_END_OF_INPUT && c != '\n')
Ed Warnickecb9cada2015-12-08 15:45:58 -0700219 ;
220}
221
222uword unformat_skip_white_space (unformat_input_t * input);
223
224/* Unformat function. */
Dave Barachc3799992016-08-15 11:12:27 -0400225typedef uword (unformat_function_t) (unformat_input_t * input,
226 va_list * args);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700227
228/* External functions. */
229
230/* General unformatting function with programmable input stream. */
Neale Ranns32e1c012016-11-22 17:07:28 +0000231uword unformat (unformat_input_t * i, const char *fmt, ...);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700232
233/* Call user defined parse function.
234 unformat_user (i, f, ...) is equivalent to unformat (i, "%U", f, ...) */
Dave Barachc3799992016-08-15 11:12:27 -0400235uword unformat_user (unformat_input_t * input, unformat_function_t * func,
236 ...);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700237
238/* Alternate version which allows for extensions. */
Neale Ranns32e1c012016-11-22 17:07:28 +0000239uword va_unformat (unformat_input_t * i, const char *fmt, va_list * args);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700240
241/* Setup for unformat of Unix style command line. */
Dave Barachc3799992016-08-15 11:12:27 -0400242void unformat_init_command_line (unformat_input_t * input, char *argv[]);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700243
244/* Setup for unformat of given string. */
BenoƮt Ganne82f618c2021-10-13 11:35:15 +0200245void unformat_init_string (unformat_input_t *input, const char *string,
246 int string_len);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700247
248always_inline void
Dave Barachc3799992016-08-15 11:12:27 -0400249unformat_init_cstring (unformat_input_t * input, char *string)
250{
251 unformat_init_string (input, string, strlen (string));
252}
Ed Warnickecb9cada2015-12-08 15:45:58 -0700253
254/* Setup for unformat of given vector string; vector will be freed by unformat_string. */
Dave Barachc3799992016-08-15 11:12:27 -0400255void unformat_init_vector (unformat_input_t * input, u8 * vector_string);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700256
257/* Format function for unformat input usable when an unformat error
258 has occurred. */
Dave Barachc3799992016-08-15 11:12:27 -0400259u8 *format_unformat_error (u8 * s, va_list * va);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700260
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. */
Dave Barachc3799992016-08-15 11:12:27 -0400265u8 *format_unformat_input (u8 * s, va_list * va);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700266
267/* Unformat (parse) function which reads a %s string and converts it
268 to and unformat_input_t. */
269unformat_function_t unformat_input;
270
271/* Parse a line ending with \n and return it. */
272unformat_function_t unformat_line;
273
274/* Parse a line ending with \n and return it as an unformat_input_t. */
275unformat_function_t unformat_line_input;
276
277/* Parse a token containing given set of characters. */
278unformat_function_t unformat_token;
279
280/* Parses a hexstring into a vector of bytes. */
281unformat_function_t unformat_hex_string;
282
283/* Returns non-zero match if input is exhausted.
284 Useful to ensure that the entire input matches with no trailing junk. */
285unformat_function_t unformat_eof;
286
287/* Parse memory size e.g. 100, 100k, 100m, 100g. */
288unformat_function_t unformat_memory_size;
289
Nathan Skrzypczak162ff5e2021-11-09 18:18:21 +0100290/* Format base 10 e.g. 100, 100K, 100M, 100G */
291u8 *format_base10 (u8 *s, va_list *va);
292
Ed Warnickecb9cada2015-12-08 15:45:58 -0700293/* Unparse memory size e.g. 100, 100k, 100m, 100g. */
Dave Barachc3799992016-08-15 11:12:27 -0400294u8 *format_memory_size (u8 * s, va_list * va);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700295
Damjan Marionb5095042020-09-11 22:13:46 +0200296/* Parse memory page size e.g. 4K, 2M */
297unformat_function_t unformat_log2_page_size;
298
299/* Unparse memory page size e.g. 4K, 2M */
300u8 *format_log2_page_size (u8 * s, va_list * va);
301
Ed Warnickecb9cada2015-12-08 15:45:58 -0700302/* Format c identifier: e.g. a_name -> "a name". */
Dave Barachc3799992016-08-15 11:12:27 -0400303u8 *format_c_identifier (u8 * s, va_list * va);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700304
Damjan Mariona7e83ce2016-06-09 12:38:22 +0200305/* Format hexdump with both hex and printable chars - compatible with text2pcap */
Dave Barachc3799992016-08-15 11:12:27 -0400306u8 *format_hexdump (u8 * s, va_list * va);
Damjan Mariona7e83ce2016-06-09 12:38:22 +0200307
Damjan Marione6387b22021-12-22 21:58:54 +0100308/* Format bitmap of array of u64 numbers */
309u8 *format_u64_bitmap (u8 *s, va_list *va);
310
Ed Warnickecb9cada2015-12-08 15:45:58 -0700311/* Unix specific formats. */
312#ifdef CLIB_UNIX
313/* Setup input from Unix file. */
Dave Barach59b25652017-09-10 15:04:27 -0400314void unformat_init_clib_file (unformat_input_t * input, int file_descriptor);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700315
316/* Take input from Unix environment variable; returns
317 1 if variable exists zero otherwise. */
Dave Barachc3799992016-08-15 11:12:27 -0400318uword unformat_init_unix_env (unformat_input_t * input, char *var);
Damjan Mariona54230d2017-06-21 11:57:07 +0200319
320/* Unformat unix group id (gid) specified as integer or string */
321unformat_function_t unformat_unix_gid;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700322#endif /* CLIB_UNIX */
323
MathiasRaoul579b1652019-10-04 09:53:45 +0000324uword unformat_data_size (unformat_input_t * input, va_list * args);
325
Ed Warnickecb9cada2015-12-08 15:45:58 -0700326/* Test code. */
327int test_format_main (unformat_input_t * input);
328int test_unformat_main (unformat_input_t * input);
329
Dave Barachc3799992016-08-15 11:12:27 -0400330/* This is not the right place for this, but putting it in vec.h
Ed Warnickecb9cada2015-12-08 15:45:58 -0700331created circular dependency problems. */
332int test_vec_main (unformat_input_t * input);
333
334#endif /* included_format_h */
Dave Barachc3799992016-08-15 11:12:27 -0400335
336/*
337 * fd.io coding-style-patch-verification: ON
338 *
339 * Local Variables:
340 * eval: (c-set-style "gnu")
341 * End:
342 */