wsutil/to_str.h

   1 /** @file
   2  *
   3  * Definitions for utilities to convert various other types to strings.
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __WSUTIL_TO_STR_H__
  13 #define __WSUTIL_TO_STR_H__
  14
  15 #include <wireshark.h>
  16
  17 #include <wsutil/wmem/wmem.h>
  18 #include <wsutil/inet_addr.h>
  19 #include <wsutil/nstime.h>
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif /* __cplusplus */
  24
  25 /**
  26  * uint8_to_hex()
  27  *
  28  * Output uint8_t hex representation to 'out', and return pointer after last character (out + 2).
  29  * It will always output full representation (padded with 0).
  30  *
  31  * String is not NUL terminated by this routine.
  32  * There needs to be at least 2 bytes in the buffer.
  33  */
  34 WS_DLL_PUBLIC char *uint8_to_hex(char *out, uint8_t val);
  35
  36 WS_DEPRECATED_X("Use uint8_to_hex instead")
  37 static inline char *guint8_to_hex(char *out, uint8_t val) { return uint8_to_hex(out, val); }
  38
  39 /**
  40  * word_to_hex()
  41  *
  42  * Output uint16_t hex representation to 'out', and return pointer after last character (out + 4).
  43  * It will always output full representation (padded with 0).
  44  *
  45  * String is not NUL terminated by this routine.
  46  * There needs to be at least 4 bytes in the buffer.
  47  */
  48 WS_DLL_PUBLIC char *word_to_hex(char *out, uint16_t word);
  49
  50 /**
  51  * word_to_hex_punct()
  52  *
  53  * Output uint16_t hex representation to 'out', and return pointer after last character.
  54  * Each byte will be separated with punct character (cannot be NUL).
  55  * It will always output full representation (padded with 0).
  56  *
  57  * String is not NUL terminated by this routine.
  58  * There needs to be at least 5 bytes in the buffer.
  59  */
  60 WS_DLL_PUBLIC char *word_to_hex_punct(char *out, uint16_t word, char punct);
  61
  62 /**
  63  * word_to_hex_npad()
  64  *
  65  * Output uint16_t hex representation to 'out', and return pointer after last character.
  66  * Value is not padded.
  67  *
  68  * String is not NUL terminated by this routine.
  69  * There needs to be at least 4 bytes in the buffer.
  70  */
  71 WS_DLL_PUBLIC char *word_to_hex_npad(char *out, uint16_t word);
  72
  73 /**
  74  * dword_to_hex()
  75  *
  76  * Output uint32_t hex representation to 'out', and return pointer after last character.
  77  * It will always output full representation (padded with 0).
  78  *
  79  * String is not NUL terminated by this routine.
  80  * There needs to be at least 8 bytes in the buffer.
  81  */
  82 WS_DLL_PUBLIC char *dword_to_hex(char *out, uint32_t dword);
  83
  84 /**
  85  * dword_to_hex_punct()
  86  *
  87  * Output uint32_t hex representation to 'out', and return pointer after last character.
  88  * Each byte will be separated with punct character (cannot be NUL).
  89  * It will always output full representation (padded with 0).
  90  *
  91  * String is not NUL terminated by this routine.
  92  * There needs to be at least 11 bytes in the buffer.
  93  */
  94 WS_DLL_PUBLIC char *dword_to_hex_punct(char *out, uint32_t dword, char punct);
  95
  96 /**
  97  * qword_to_hex()
  98  *
  99  * Output uint64_t hex representation to 'out', and return pointer after last character.
 100  * It will always output full representation (padded with 0).
 101  *
 102  * String is not NUL terminated by this routine.
 103  * There needs to be at least 16 bytes in the buffer.
 104  */
 105 WS_DLL_PUBLIC char *qword_to_hex(char *out, uint64_t qword);
 106
 107 /**
 108  * qword_to_hex_punct()
 109  *
 110  * Output uint64_t hex representation to 'out', and return pointer after last character.
 111  * Each byte will be separated with punct character (cannot be NUL).
 112  * It will always output full representation (padded with 0).
 113  *
 114  * String is not NUL terminated by this routine.
 115  * There needs to be at least 22 bytes in the buffer.
 116  */
 117 WS_DLL_PUBLIC char *qword_to_hex_punct(char *out, uint64_t qword, char punct);
 118
 119 /**
 120  * bytes_to_hexstr()
 121  *
 122  * Output hex representation of uint8_t array, and return pointer after last character.
 123  * It will always output full representation (padded with 0).
 124  *
 125  * String is not NUL terminated by this routine.
 126  * There needs to be at least len * 2 bytes in the buffer.
 127  */
 128 WS_DLL_PUBLIC char *bytes_to_hexstr(char *out, const uint8_t *ad, size_t len);
 129
 130 /**
 131  * bytes_to_hexstr_punct()
 132  *
 133  * Output hex representation of uint8_t array, and return pointer after last character.
 134  * Each byte will be separated with punct character (cannot be NUL).
 135  * It will always output full representation (padded with 0).
 136  *
 137  * String is not NUL terminated by this routine.
 138  * There needs to be at least len * 3 - 1 bytes in the buffer.
 139  */
 140 WS_DLL_PUBLIC char *bytes_to_hexstr_punct(char *out, const uint8_t *ad, size_t len, char punct);
 141
 142 /** Turn an array of bytes into a string showing the bytes in hex,
 143  *  separated by a punctuation character.
 144  *
 145  * @param scope memory allocation scheme used
 146  * @param buf A pointer to the byte array
 147  * @param buf_size The length of the byte array
 148  * @param punct The punctuation character
 149  * @param max_bytes_len Maximum number of bytes to represent, zero for no limit.
 150  * @return A pointer to the formatted string
 151  */
 152 WS_DLL_PUBLIC char *bytes_to_str_punct_maxlen(wmem_allocator_t *scope,
 153                                 const uint8_t *buf, size_t buf_size,
 154                                 char punct, size_t max_bytes_len);
 155
 156 #define bytes_to_str_punct(scope, buf, buf_size, punct) \
 157     bytes_to_str_punct_maxlen(scope, buf, buf_size, punct, 24)
 158
 159 /** Turn an array of bytes into a string showing the bytes in hex.
 160  *
 161  * @param scope memory allocation scheme used
 162  * @param buf A pointer to the byte array
 163  * @param buf_size The length of the byte array
 164  * @param max_bytes_len Maximum number of bytes to represent, zero for no limit.
 165  * @return A pointer to the formatted string
 166  */
 167 WS_DLL_PUBLIC char *bytes_to_str_maxlen(wmem_allocator_t *scope,
 168                                 const uint8_t *buf, size_t buf_size,
 169                                 size_t max_bytes_len);
 170
 171 #define bytes_to_str(scope, buf, buf_size) \
 172     bytes_to_str_maxlen(scope, buf, buf_size, 36)
 173
 174 /**
 175  * oct_to_str_back()
 176  *
 177  * Output uint32_t octal representation backward (last character will be written on ptr - 1),
 178  * and return pointer to first character.
 179  *
 180  * String is not NUL terminated by this routine.
 181  * There needs to be at least 12 bytes in the buffer.
 182  */
 183 WS_DLL_PUBLIC char *oct_to_str_back(char *ptr, uint32_t value);
 184
 185 /**
 186  * oct64_to_str_back()
 187  *
 188  * Output uint64_t octal representation backward (last character will be written on ptr - 1),
 189  * and return pointer to first character.
 190  *
 191  * String is not NUL terminated by this routine.
 192  * There needs to be at least 12 bytes in the buffer.
 193  */
 194 WS_DLL_PUBLIC char *oct64_to_str_back(char *ptr, uint64_t value);
 195
 196 /**
 197  * hex_to_str_back()
 198  *
 199  * Output uint32_t hex representation backward (last character will be written on ptr - 1),
 200  * and return pointer to first character.
 201  * This routine will output for sure (can output more) 'len' decimal characters (number padded with '0').
 202  *
 203  * String is not NUL terminated by this routine.
 204  * There needs to be at least 2 + MAX(8, len) bytes in the buffer.
 205  */
 206 WS_DLL_PUBLIC char *hex_to_str_back_len(char *ptr, uint32_t value, int len);
 207
 208 /**
 209  * hex64_to_str_back()
 210  *
 211  * Output uint64_t hex representation backward (last character will be written on ptr - 1),
 212  * and return pointer to first character.
 213  * This routine will output for sure (can output more) 'len' decimal characters (number padded with '0').
 214  *
 215  * String is not NUL terminated by this routine.
 216  * There needs to be at least 2 + MAX(16, len) bytes in the buffer.
 217  */
 218 WS_DLL_PUBLIC char *hex64_to_str_back_len(char *ptr, uint64_t value, int len);
 219
 220 /**
 221  * uint_to_str_back()
 222  *
 223  * Output uint32_t decimal representation backward (last character will be written on ptr - 1),
 224  * and return pointer to first character.
 225  *
 226  * String is not NUL terminated by this routine.
 227  * There needs to be at least 10 bytes in the buffer.
 228  */
 229 WS_DLL_PUBLIC char *uint_to_str_back(char *ptr, uint32_t value);
 230
 231 /**
 232  * uint64_str_back()
 233  *
 234  * Output uint64_t decimal representation backward (last character will be written on ptr - 1),
 235  * and return pointer to first character.
 236  *
 237  * String is not NUL terminated by this routine.
 238  * There needs to be at least 20 bytes in the buffer.
 239  */
 240 WS_DLL_PUBLIC char *uint64_to_str_back(char *ptr, uint64_t value);
 241
 242 /**
 243  * uint_to_str_back_len()
 244  *
 245  * Output uint32_t decimal representation backward (last character will be written on ptr - 1),
 246  * and return pointer to first character.
 247  * This routine will output for sure (can output more) 'len' decimal characters (number padded with '0').
 248  *
 249  * String is not NUL terminated by this routine.
 250  * There needs to be at least MAX(10, len) bytes in the buffer.
 251  */
 252 WS_DLL_PUBLIC char *uint_to_str_back_len(char *ptr, uint32_t value, int len);
 253
 254 /**
 255  * uint64_to_str_back_len()
 256  *
 257  * Output uint64_t decimal representation backward (last character will be written on ptr - 1),
 258  * and return pointer to first character.
 259  * This routine will output for sure (can output more) 'len' decimal characters (number padded with '0').
 260  *
 261  * String is not NUL terminated by this routine.
 262  * There needs to be at least MAX(20, len) bytes in the buffer.
 263  */
 264 WS_DLL_PUBLIC char *uint64_to_str_back_len(char *ptr, uint64_t value, int len);
 265
 266 /**
 267  * int_to_str_back()
 268  *
 269  * Output int32_t decimal representation backward (last character will be written on ptr - 1),
 270  * and return pointer to first character.
 271  *
 272  * String is not NUL terminated by this routine.
 273  * There needs to be at least 11 bytes in the buffer.
 274  */
 275 WS_DLL_PUBLIC char *int_to_str_back(char *ptr, int32_t value);
 276
 277 /**
 278  * int64_to_str_back()
 279  *
 280  * Output int64_t decimal representation backward (last character will be written on ptr - 1),
 281  * and return pointer to first character.
 282  *
 283  * String is not NUL terminated by this routine.
 284  * There needs to be at least 21 bytes in the buffer.
 285  */
 286 WS_DLL_PUBLIC char *int64_to_str_back(char *ptr, int64_t value);
 287
 288 WS_DLL_PUBLIC void uint32_to_str_buf(uint32_t u, char *buf, size_t buf_len);
 289
 290 WS_DEPRECATED_X("Use uint32_to_str_buf instead")
 291 static inline void guint32_to_str_buf(uint32_t u, char *buf, size_t buf_len) { uint32_to_str_buf(u, buf, buf_len); }
 292
 293 WS_DLL_PUBLIC void uint64_to_str_buf(uint64_t u, char *buf, size_t buf_len);
 294
 295 WS_DEPRECATED_X("Use uint64_to_str_buf instead")
 296 static inline void guint64_to_str_buf(uint64_t u, char *buf, size_t buf_len) { uint64_to_str_buf(u, buf, buf_len); }
 297
 298 WS_DEPRECATED_X("Use ip_num_to_str_buf() or ip_addr_to_str() instead")
 299 WS_DLL_PUBLIC void ip_to_str_buf(const uint8_t *ad, char *buf, const int buf_len);
 300
 301 WS_DEPRECATED_X("Use ip_num_to_str() or ip_addr_to_str() instead")
 302 WS_DLL_PUBLIC char *ip_to_str(wmem_allocator_t *scope, const uint8_t *ad);
 303
 304 /* Host byte order */
 305 WS_DLL_PUBLIC void ip_num_to_str_buf(uint32_t ad, char *buf, const int buf_len);
 306
 307 /* Host byte order */
 308 WS_DLL_PUBLIC char *ip_num_to_str(wmem_allocator_t *scope, uint32_t ad);
 309
 310 WS_DLL_PUBLIC void ip_addr_to_str_buf(const ws_in4_addr *ad, char *buf, const int buf_len);
 311
 312 WS_DLL_PUBLIC char *ip_addr_to_str(wmem_allocator_t *scope, const ws_in4_addr *ad);
 313
 314 WS_DLL_PUBLIC void ip6_to_str_buf(const ws_in6_addr *ad, char *buf, size_t buf_size);
 315
 316 WS_DLL_PUBLIC char *ip6_to_str(wmem_allocator_t *scope, const ws_in6_addr *ad);
 317
 318 WS_DLL_PUBLIC char *ipxnet_to_str_punct(wmem_allocator_t *scope, const uint32_t ad, const char punct);
 319
 320 WS_DLL_PUBLIC char *eui64_to_str(wmem_allocator_t *scope, const uint64_t ad);
 321
 322 WS_DLL_PUBLIC int format_fractional_part_nsecs(char *, size_t, uint32_t, const char *, int);
 323
 324 WS_DLL_PUBLIC void display_epoch_time(char *, size_t, const nstime_t *, int);
 325
 326 WS_DLL_PUBLIC void display_signed_time(char *, size_t, const nstime_t *, int);
 327
 328 WS_DLL_PUBLIC void format_nstime_as_iso8601(char *, size_t, const nstime_t *, char *, bool, int);
 329
 330 #ifdef __cplusplus
 331 }
 332 #endif /* __cplusplus */
 333
 334 #endif /* __TO_STR_H__  */