lib/string_helpers.c

   1 /*
   2  * Helpers for formatting and printing strings
   3  *
   4  * Copyright 31 August 2008 James Bottomley
   5  * Copyright (C) 2013, Intel Corporation
   6  */
   7 #include <linux/kernel.h>
   8 #include <linux/math64.h>
   9 #include <linux/export.h>
  10 #include <linux/ctype.h>
  11 #include <linux/errno.h>
  12 #include <linux/string.h>
  13 #include <linux/string_helpers.h>
  14
  15 /**
  16  * string_get_size - get the size in the specified units
  17  * @size:       The size to be converted
  18  * @units:      units to use (powers of 1000 or 1024)
  19  * @buf:        buffer to format to
  20  * @len:        length of buffer
  21  *
  22  * This function returns a string formatted to 3 significant figures
  23  * giving the size in the required units.  Returns 0 on success or
  24  * error on failure.  @buf is always zero terminated.
  25  *
  26  */
  27 int string_get_size(u64 size, const enum string_size_units units,
  28                     char *buf, int len)
  29 {
  30         static const char *const units_10[] = {
  31                 "B", "kB", "MB", "GB", "TB", "PB", "EB"
  32         };
  33         static const char *const units_2[] = {
  34                 "B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB"
  35         };
  36         static const char *const *const units_str[] = {
  37                 [STRING_UNITS_10] = units_10,
  38                 [STRING_UNITS_2] = units_2,
  39         };
  40         static const unsigned int divisor[] = {
  41                 [STRING_UNITS_10] = 1000,
  42                 [STRING_UNITS_2] = 1024,
  43         };
  44         int i, j;
  45         u32 remainder = 0, sf_cap;
  46         char tmp[8];
  47
  48         tmp[0] = '\0';
  49         i = 0;
  50         if (size >= divisor[units]) {
  51                 while (size >= divisor[units]) {
  52                         remainder = do_div(size, divisor[units]);
  53                         i++;
  54                 }
  55
  56                 sf_cap = size;
  57                 for (j = 0; sf_cap*10 < 1000; j++)
  58                         sf_cap *= 10;
  59
  60                 if (j) {
  61                         remainder *= 1000;
  62                         remainder /= divisor[units];
  63                         snprintf(tmp, sizeof(tmp), ".%03u", remainder);
  64                         tmp[j+1] = '\0';
  65                 }
  66         }
  67
  68         snprintf(buf, len, "%u%s %s", (u32)size,
  69                  tmp, units_str[units][i]);
  70
  71         return 0;
  72 }
  73 EXPORT_SYMBOL(string_get_size);
  74
  75 static bool unescape_space(char **src, char **dst)
  76 {
  77         char *p = *dst, *q = *src;
  78
  79         switch (*q) {
  80         case 'n':
  81                 *p = '\n';
  82                 break;
  83         case 'r':
  84                 *p = '\r';
  85                 break;
  86         case 't':
  87                 *p = '\t';
  88                 break;
  89         case 'v':
  90                 *p = '\v';
  91                 break;
  92         case 'f':
  93                 *p = '\f';
  94                 break;
  95         default:
  96                 return false;
  97         }
  98         *dst += 1;
  99         *src += 1;
 100         return true;
 101 }
 102
 103 static bool unescape_octal(char **src, char **dst)
 104 {
 105         char *p = *dst, *q = *src;
 106         u8 num;
 107
 108         if (isodigit(*q) == 0)
 109                 return false;
 110
 111         num = (*q++) & 7;
 112         while (num < 32 && isodigit(*q) && (q - *src < 3)) {
 113                 num <<= 3;
 114                 num += (*q++) & 7;
 115         }
 116         *p = num;
 117         *dst += 1;
 118         *src = q;
 119         return true;
 120 }
 121
 122 static bool unescape_hex(char **src, char **dst)
 123 {
 124         char *p = *dst, *q = *src;
 125         int digit;
 126         u8 num;
 127
 128         if (*q++ != 'x')
 129                 return false;
 130
 131         num = digit = hex_to_bin(*q++);
 132         if (digit < 0)
 133                 return false;
 134
 135         digit = hex_to_bin(*q);
 136         if (digit >= 0) {
 137                 q++;
 138                 num = (num << 4) | digit;
 139         }
 140         *p = num;
 141         *dst += 1;
 142         *src = q;
 143         return true;
 144 }
 145
 146 static bool unescape_special(char **src, char **dst)
 147 {
 148         char *p = *dst, *q = *src;
 149
 150         switch (*q) {
 151         case '\"':
 152                 *p = '\"';
 153                 break;
 154         case '\\':
 155                 *p = '\\';
 156                 break;
 157         case 'a':
 158                 *p = '\a';
 159                 break;
 160         case 'e':
 161                 *p = '\e';
 162                 break;
 163         default:
 164                 return false;
 165         }
 166         *dst += 1;
 167         *src += 1;
 168         return true;
 169 }
 170
 171 /**
 172  * string_unescape - unquote characters in the given string
 173  * @src:        source buffer (escaped)
 174  * @dst:        destination buffer (unescaped)
 175  * @size:       size of the destination buffer (0 to unlimit)
 176  * @flags:      combination of the flags (bitwise OR):
 177  *      %UNESCAPE_SPACE:
 178  *              '\f' - form feed
 179  *              '\n' - new line
 180  *              '\r' - carriage return
 181  *              '\t' - horizontal tab
 182  *              '\v' - vertical tab
 183  *      %UNESCAPE_OCTAL:
 184  *              '\NNN' - byte with octal value NNN (1 to 3 digits)
 185  *      %UNESCAPE_HEX:
 186  *              '\xHH' - byte with hexadecimal value HH (1 to 2 digits)
 187  *      %UNESCAPE_SPECIAL:
 188  *              '\"' - double quote
 189  *              '\\' - backslash
 190  *              '\a' - alert (BEL)
 191  *              '\e' - escape
 192  *      %UNESCAPE_ANY:
 193  *              all previous together
 194  *
 195  * Description:
 196  * The function unquotes characters in the given string.
 197  *
 198  * Because the size of the output will be the same as or less than the size of
 199  * the input, the transformation may be performed in place.
 200  *
 201  * Caller must provide valid source and destination pointers. Be aware that
 202  * destination buffer will always be NULL-terminated. Source string must be
 203  * NULL-terminated as well.
 204  *
 205  * Return:
 206  * The amount of the characters processed to the destination buffer excluding
 207  * trailing '\0' is returned.
 208  */
 209 int string_unescape(char *src, char *dst, size_t size, unsigned int flags)
 210 {
 211         char *out = dst;
 212
 213         while (*src && --size) {
 214                 if (src[0] == '\\' && src[1] != '\0' && size > 1) {
 215                         src++;
 216                         size--;
 217
 218                         if (flags & UNESCAPE_SPACE &&
 219                                         unescape_space(&src, &out))
 220                                 continue;
 221
 222                         if (flags & UNESCAPE_OCTAL &&
 223                                         unescape_octal(&src, &out))
 224                                 continue;
 225
 226                         if (flags & UNESCAPE_HEX &&
 227                                         unescape_hex(&src, &out))
 228                                 continue;
 229
 230                         if (flags & UNESCAPE_SPECIAL &&
 231                                         unescape_special(&src, &out))
 232                                 continue;
 233
 234                         *out++ = '\\';
 235                 }
 236                 *out++ = *src++;
 237         }
 238         *out = '\0';
 239
 240         return out - dst;
 241 }
 242 EXPORT_SYMBOL(string_unescape);
 243
 244 static int escape_passthrough(unsigned char c, char **dst, size_t *osz)
 245 {
 246         char *out = *dst;
 247
 248         if (*osz < 1)
 249                 return -ENOMEM;
 250
 251         *out++ = c;
 252
 253         *dst = out;
 254         *osz -= 1;
 255
 256         return 1;
 257 }
 258
 259 static int escape_space(unsigned char c, char **dst, size_t *osz)
 260 {
 261         char *out = *dst;
 262         unsigned char to;
 263
 264         if (*osz < 2)
 265                 return -ENOMEM;
 266
 267         switch (c) {
 268         case '\n':
 269                 to = 'n';
 270                 break;
 271         case '\r':
 272                 to = 'r';
 273                 break;
 274         case '\t':
 275                 to = 't';
 276                 break;
 277         case '\v':
 278                 to = 'v';
 279                 break;
 280         case '\f':
 281                 to = 'f';
 282                 break;
 283         default:
 284                 return 0;
 285         }
 286
 287         *out++ = '\\';
 288         *out++ = to;
 289
 290         *dst = out;
 291         *osz -= 2;
 292
 293         return 1;
 294 }
 295
 296 static int escape_special(unsigned char c, char **dst, size_t *osz)
 297 {
 298         char *out = *dst;
 299         unsigned char to;
 300
 301         if (*osz < 2)
 302                 return -ENOMEM;
 303
 304         switch (c) {
 305         case '\\':
 306                 to = '\\';
 307                 break;
 308         case '\a':
 309                 to = 'a';
 310                 break;
 311         case '\e':
 312                 to = 'e';
 313                 break;
 314         default:
 315                 return 0;
 316         }
 317
 318         *out++ = '\\';
 319         *out++ = to;
 320
 321         *dst = out;
 322         *osz -= 2;
 323
 324         return 1;
 325 }
 326
 327 static int escape_null(unsigned char c, char **dst, size_t *osz)
 328 {
 329         char *out = *dst;
 330
 331         if (*osz < 2)
 332                 return -ENOMEM;
 333
 334         if (c)
 335                 return 0;
 336
 337         *out++ = '\\';
 338         *out++ = '0';
 339
 340         *dst = out;
 341         *osz -= 2;
 342
 343         return 1;
 344 }
 345
 346 static int escape_octal(unsigned char c, char **dst, size_t *osz)
 347 {
 348         char *out = *dst;
 349
 350         if (*osz < 4)
 351                 return -ENOMEM;
 352
 353         *out++ = '\\';
 354         *out++ = ((c >> 6) & 0x07) + '0';
 355         *out++ = ((c >> 3) & 0x07) + '0';
 356         *out++ = ((c >> 0) & 0x07) + '0';
 357
 358         *dst = out;
 359         *osz -= 4;
 360
 361         return 1;
 362 }
 363
 364 static int escape_hex(unsigned char c, char **dst, size_t *osz)
 365 {
 366         char *out = *dst;
 367
 368         if (*osz < 4)
 369                 return -ENOMEM;
 370
 371         *out++ = '\\';
 372         *out++ = 'x';
 373         *out++ = hex_asc_hi(c);
 374         *out++ = hex_asc_lo(c);
 375
 376         *dst = out;
 377         *osz -= 4;
 378
 379         return 1;
 380 }
 381
 382 /**
 383  * string_escape_mem - quote characters in the given memory buffer
 384  * @src:        source buffer (unescaped)
 385  * @isz:        source buffer size
 386  * @dst:        destination buffer (escaped)
 387  * @osz:        destination buffer size
 388  * @flags:      combination of the flags (bitwise OR):
 389  *      %ESCAPE_SPACE:
 390  *              '\f' - form feed
 391  *              '\n' - new line
 392  *              '\r' - carriage return
 393  *              '\t' - horizontal tab
 394  *              '\v' - vertical tab
 395  *      %ESCAPE_SPECIAL:
 396  *              '\\' - backslash
 397  *              '\a' - alert (BEL)
 398  *              '\e' - escape
 399  *      %ESCAPE_NULL:
 400  *              '\0' - null
 401  *      %ESCAPE_OCTAL:
 402  *              '\NNN' - byte with octal value NNN (3 digits)
 403  *      %ESCAPE_ANY:
 404  *              all previous together
 405  *      %ESCAPE_NP:
 406  *              escape only non-printable characters (checked by isprint)
 407  *      %ESCAPE_ANY_NP:
 408  *              all previous together
 409  *      %ESCAPE_HEX:
 410  *              '\xHH' - byte with hexadecimal value HH (2 digits)
 411  * @esc:        NULL-terminated string of characters any of which, if found in
 412  *              the source, has to be escaped
 413  *
 414  * Description:
 415  * The process of escaping byte buffer includes several parts. They are applied
 416  * in the following sequence.
 417  *      1. The character is matched to the printable class, if asked, and in
 418  *         case of match it passes through to the output.
 419  *      2. The character is not matched to the one from @esc string and thus
 420  *         must go as is to the output.
 421  *      3. The character is checked if it falls into the class given by @flags.
 422  *         %ESCAPE_OCTAL and %ESCAPE_HEX are going last since they cover any
 423  *         character. Note that they actually can't go together, otherwise
 424  *         %ESCAPE_HEX will be ignored.
 425  *
 426  * Caller must provide valid source and destination pointers. Be aware that
 427  * destination buffer will not be NULL-terminated, thus caller have to append
 428  * it if needs.
 429  *
 430  * Return:
 431  * The amount of the characters processed to the destination buffer, or
 432  * %-ENOMEM if the size of buffer is not enough to put an escaped character is
 433  * returned.
 434  *
 435  * Even in the case of error @dst pointer will be updated to point to the byte
 436  * after the last processed character.
 437  */
 438 int string_escape_mem(const char *src, size_t isz, char **dst, size_t osz,
 439                       unsigned int flags, const char *esc)
 440 {
 441         char *out = *dst, *p = out;
 442         bool is_dict = esc && *esc;
 443         int ret = 0;
 444
 445         while (isz--) {
 446                 unsigned char c = *src++;
 447
 448                 /*
 449                  * Apply rules in the following sequence:
 450                  *      - the character is printable, when @flags has
 451                  *        %ESCAPE_NP bit set
 452                  *      - the @esc string is supplied and does not contain a
 453                  *        character under question
 454                  *      - the character doesn't fall into a class of symbols
 455                  *        defined by given @flags
 456                  * In these cases we just pass through a character to the
 457                  * output buffer.
 458                  */
 459                 if ((flags & ESCAPE_NP && isprint(c)) ||
 460                     (is_dict && !strchr(esc, c))) {
 461                         /* do nothing */
 462                 } else {
 463                         if (flags & ESCAPE_SPACE) {
 464                                 ret = escape_space(c, &p, &osz);
 465                                 if (ret < 0)
 466                                         break;
 467                                 if (ret > 0)
 468                                         continue;
 469                         }
 470
 471                         if (flags & ESCAPE_SPECIAL) {
 472                                 ret = escape_special(c, &p, &osz);
 473                                 if (ret < 0)
 474                                         break;
 475                                 if (ret > 0)
 476                                         continue;
 477                         }
 478
 479                         if (flags & ESCAPE_NULL) {
 480                                 ret = escape_null(c, &p, &osz);
 481                                 if (ret < 0)
 482                                         break;
 483                                 if (ret > 0)
 484                                         continue;
 485                         }
 486
 487                         /* ESCAPE_OCTAL and ESCAPE_HEX always go last */
 488                         if (flags & ESCAPE_OCTAL) {
 489                                 ret = escape_octal(c, &p, &osz);
 490                                 if (ret < 0)
 491                                         break;
 492                                 continue;
 493                         }
 494                         if (flags & ESCAPE_HEX) {
 495                                 ret = escape_hex(c, &p, &osz);
 496                                 if (ret < 0)
 497                                         break;
 498                                 continue;
 499                         }
 500                 }
 501
 502                 ret = escape_passthrough(c, &p, &osz);
 503                 if (ret < 0)
 504                         break;
 505         }
 506
 507         *dst = p;
 508
 509         if (ret < 0)
 510                 return ret;
 511
 512         return p - out;
 513 }
 514 EXPORT_SYMBOL(string_escape_mem);