lib/string_helpers.c

   1 // SPDX-License-Identifier: GPL-2.0-only
   2 /*
   3  * Helpers for formatting and printing strings
   4  *
   5  * Copyright 31 August 2008 James Bottomley
   6  * Copyright (C) 2013, Intel Corporation
   7  */
   8 #include <linux/bug.h>
   9 #include <linux/kernel.h>
  10 #include <linux/math64.h>
  11 #include <linux/export.h>
  12 #include <linux/ctype.h>
  13 #include <linux/errno.h>
  14 #include <linux/fs.h>
  15 #include <linux/limits.h>
  16 #include <linux/mm.h>
  17 #include <linux/slab.h>
  18 #include <linux/string.h>
  19 #include <linux/string_helpers.h>
  20
  21 /**
  22  * string_get_size - get the size in the specified units
  23  * @size:       The size to be converted in blocks
  24  * @blk_size:   Size of the block (use 1 for size in bytes)
  25  * @units:      units to use (powers of 1000 or 1024)
  26  * @buf:        buffer to format to
  27  * @len:        length of buffer
  28  *
  29  * This function returns a string formatted to 3 significant figures
  30  * giving the size in the required units.  @buf should have room for
  31  * at least 9 bytes and will always be zero terminated.
  32  *
  33  */
  34 void string_get_size(u64 size, u64 blk_size, const enum string_size_units units,
  35                      char *buf, int len)
  36 {
  37         static const char *const units_10[] = {
  38                 "B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"
  39         };
  40         static const char *const units_2[] = {
  41                 "B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"
  42         };
  43         static const char *const *const units_str[] = {
  44                 [STRING_UNITS_10] = units_10,
  45                 [STRING_UNITS_2] = units_2,
  46         };
  47         static const unsigned int divisor[] = {
  48                 [STRING_UNITS_10] = 1000,
  49                 [STRING_UNITS_2] = 1024,
  50         };
  51         static const unsigned int rounding[] = { 500, 50, 5 };
  52         int i = 0, j;
  53         u32 remainder = 0, sf_cap;
  54         char tmp[8];
  55         const char *unit;
  56
  57         tmp[0] = '\0';
  58
  59         if (blk_size == 0)
  60                 size = 0;
  61         if (size == 0)
  62                 goto out;
  63
  64         /* This is Napier's algorithm.  Reduce the original block size to
  65          *
  66          * coefficient * divisor[units]^i
  67          *
  68          * we do the reduction so both coefficients are just under 32 bits so
  69          * that multiplying them together won't overflow 64 bits and we keep
  70          * as much precision as possible in the numbers.
  71          *
  72          * Note: it's safe to throw away the remainders here because all the
  73          * precision is in the coefficients.
  74          */
  75         while (blk_size >> 32) {
  76                 do_div(blk_size, divisor[units]);
  77                 i++;
  78         }
  79
  80         while (size >> 32) {
  81                 do_div(size, divisor[units]);
  82                 i++;
  83         }
  84
  85         /* now perform the actual multiplication keeping i as the sum of the
  86          * two logarithms */
  87         size *= blk_size;
  88
  89         /* and logarithmically reduce it until it's just under the divisor */
  90         while (size >= divisor[units]) {
  91                 remainder = do_div(size, divisor[units]);
  92                 i++;
  93         }
  94
  95         /* work out in j how many digits of precision we need from the
  96          * remainder */
  97         sf_cap = size;
  98         for (j = 0; sf_cap*10 < 1000; j++)
  99                 sf_cap *= 10;
 100
 101         if (units == STRING_UNITS_2) {
 102                 /* express the remainder as a decimal.  It's currently the
 103                  * numerator of a fraction whose denominator is
 104                  * divisor[units], which is 1 << 10 for STRING_UNITS_2 */
 105                 remainder *= 1000;
 106                 remainder >>= 10;
 107         }
 108
 109         /* add a 5 to the digit below what will be printed to ensure
 110          * an arithmetical round up and carry it through to size */
 111         remainder += rounding[j];
 112         if (remainder >= 1000) {
 113                 remainder -= 1000;
 114                 size += 1;
 115         }
 116
 117         if (j) {
 118                 snprintf(tmp, sizeof(tmp), ".%03u", remainder);
 119                 tmp[j+1] = '\0';
 120         }
 121
 122  out:
 123         if (i >= ARRAY_SIZE(units_2))
 124                 unit = "UNK";
 125         else
 126                 unit = units_str[units][i];
 127
 128         snprintf(buf, len, "%u%s %s", (u32)size,
 129                  tmp, unit);
 130 }
 131 EXPORT_SYMBOL(string_get_size);
 132
 133 static bool unescape_space(char **src, char **dst)
 134 {
 135         char *p = *dst, *q = *src;
 136
 137         switch (*q) {
 138         case 'n':
 139                 *p = '\n';
 140                 break;
 141         case 'r':
 142                 *p = '\r';
 143                 break;
 144         case 't':
 145                 *p = '\t';
 146                 break;
 147         case 'v':
 148                 *p = '\v';
 149                 break;
 150         case 'f':
 151                 *p = '\f';
 152                 break;
 153         default:
 154                 return false;
 155         }
 156         *dst += 1;
 157         *src += 1;
 158         return true;
 159 }
 160
 161 static bool unescape_octal(char **src, char **dst)
 162 {
 163         char *p = *dst, *q = *src;
 164         u8 num;
 165
 166         if (isodigit(*q) == 0)
 167                 return false;
 168
 169         num = (*q++) & 7;
 170         while (num < 32 && isodigit(*q) && (q - *src < 3)) {
 171                 num <<= 3;
 172                 num += (*q++) & 7;
 173         }
 174         *p = num;
 175         *dst += 1;
 176         *src = q;
 177         return true;
 178 }
 179
 180 static bool unescape_hex(char **src, char **dst)
 181 {
 182         char *p = *dst, *q = *src;
 183         int digit;
 184         u8 num;
 185
 186         if (*q++ != 'x')
 187                 return false;
 188
 189         num = digit = hex_to_bin(*q++);
 190         if (digit < 0)
 191                 return false;
 192
 193         digit = hex_to_bin(*q);
 194         if (digit >= 0) {
 195                 q++;
 196                 num = (num << 4) | digit;
 197         }
 198         *p = num;
 199         *dst += 1;
 200         *src = q;
 201         return true;
 202 }
 203
 204 static bool unescape_special(char **src, char **dst)
 205 {
 206         char *p = *dst, *q = *src;
 207
 208         switch (*q) {
 209         case '\"':
 210                 *p = '\"';
 211                 break;
 212         case '\\':
 213                 *p = '\\';
 214                 break;
 215         case 'a':
 216                 *p = '\a';
 217                 break;
 218         case 'e':
 219                 *p = '\e';
 220                 break;
 221         default:
 222                 return false;
 223         }
 224         *dst += 1;
 225         *src += 1;
 226         return true;
 227 }
 228
 229 /**
 230  * string_unescape - unquote characters in the given string
 231  * @src:        source buffer (escaped)
 232  * @dst:        destination buffer (unescaped)
 233  * @size:       size of the destination buffer (0 to unlimit)
 234  * @flags:      combination of the flags.
 235  *
 236  * Description:
 237  * The function unquotes characters in the given string.
 238  *
 239  * Because the size of the output will be the same as or less than the size of
 240  * the input, the transformation may be performed in place.
 241  *
 242  * Caller must provide valid source and destination pointers. Be aware that
 243  * destination buffer will always be NULL-terminated. Source string must be
 244  * NULL-terminated as well.  The supported flags are::
 245  *
 246  *      UNESCAPE_SPACE:
 247  *              '\f' - form feed
 248  *              '\n' - new line
 249  *              '\r' - carriage return
 250  *              '\t' - horizontal tab
 251  *              '\v' - vertical tab
 252  *      UNESCAPE_OCTAL:
 253  *              '\NNN' - byte with octal value NNN (1 to 3 digits)
 254  *      UNESCAPE_HEX:
 255  *              '\xHH' - byte with hexadecimal value HH (1 to 2 digits)
 256  *      UNESCAPE_SPECIAL:
 257  *              '\"' - double quote
 258  *              '\\' - backslash
 259  *              '\a' - alert (BEL)
 260  *              '\e' - escape
 261  *      UNESCAPE_ANY:
 262  *              all previous together
 263  *
 264  * Return:
 265  * The amount of the characters processed to the destination buffer excluding
 266  * trailing '\0' is returned.
 267  */
 268 int string_unescape(char *src, char *dst, size_t size, unsigned int flags)
 269 {
 270         char *out = dst;
 271
 272         while (*src && --size) {
 273                 if (src[0] == '\\' && src[1] != '\0' && size > 1) {
 274                         src++;
 275                         size--;
 276
 277                         if (flags & UNESCAPE_SPACE &&
 278                                         unescape_space(&src, &out))
 279                                 continue;
 280
 281                         if (flags & UNESCAPE_OCTAL &&
 282                                         unescape_octal(&src, &out))
 283                                 continue;
 284
 285                         if (flags & UNESCAPE_HEX &&
 286                                         unescape_hex(&src, &out))
 287                                 continue;
 288
 289                         if (flags & UNESCAPE_SPECIAL &&
 290                                         unescape_special(&src, &out))
 291                                 continue;
 292
 293                         *out++ = '\\';
 294                 }
 295                 *out++ = *src++;
 296         }
 297         *out = '\0';
 298
 299         return out - dst;
 300 }
 301 EXPORT_SYMBOL(string_unescape);
 302
 303 static bool escape_passthrough(unsigned char c, char **dst, char *end)
 304 {
 305         char *out = *dst;
 306
 307         if (out < end)
 308                 *out = c;
 309         *dst = out + 1;
 310         return true;
 311 }
 312
 313 static bool escape_space(unsigned char c, char **dst, char *end)
 314 {
 315         char *out = *dst;
 316         unsigned char to;
 317
 318         switch (c) {
 319         case '\n':
 320                 to = 'n';
 321                 break;
 322         case '\r':
 323                 to = 'r';
 324                 break;
 325         case '\t':
 326                 to = 't';
 327                 break;
 328         case '\v':
 329                 to = 'v';
 330                 break;
 331         case '\f':
 332                 to = 'f';
 333                 break;
 334         default:
 335                 return false;
 336         }
 337
 338         if (out < end)
 339                 *out = '\\';
 340         ++out;
 341         if (out < end)
 342                 *out = to;
 343         ++out;
 344
 345         *dst = out;
 346         return true;
 347 }
 348
 349 static bool escape_special(unsigned char c, char **dst, char *end)
 350 {
 351         char *out = *dst;
 352         unsigned char to;
 353
 354         switch (c) {
 355         case '\\':
 356                 to = '\\';
 357                 break;
 358         case '\a':
 359                 to = 'a';
 360                 break;
 361         case '\e':
 362                 to = 'e';
 363                 break;
 364         case '"':
 365                 to = '"';
 366                 break;
 367         default:
 368                 return false;
 369         }
 370
 371         if (out < end)
 372                 *out = '\\';
 373         ++out;
 374         if (out < end)
 375                 *out = to;
 376         ++out;
 377
 378         *dst = out;
 379         return true;
 380 }
 381
 382 static bool escape_null(unsigned char c, char **dst, char *end)
 383 {
 384         char *out = *dst;
 385
 386         if (c)
 387                 return false;
 388
 389         if (out < end)
 390                 *out = '\\';
 391         ++out;
 392         if (out < end)
 393                 *out = '0';
 394         ++out;
 395
 396         *dst = out;
 397         return true;
 398 }
 399
 400 static bool escape_octal(unsigned char c, char **dst, char *end)
 401 {
 402         char *out = *dst;
 403
 404         if (out < end)
 405                 *out = '\\';
 406         ++out;
 407         if (out < end)
 408                 *out = ((c >> 6) & 0x07) + '0';
 409         ++out;
 410         if (out < end)
 411                 *out = ((c >> 3) & 0x07) + '0';
 412         ++out;
 413         if (out < end)
 414                 *out = ((c >> 0) & 0x07) + '0';
 415         ++out;
 416
 417         *dst = out;
 418         return true;
 419 }
 420
 421 static bool escape_hex(unsigned char c, char **dst, char *end)
 422 {
 423         char *out = *dst;
 424
 425         if (out < end)
 426                 *out = '\\';
 427         ++out;
 428         if (out < end)
 429                 *out = 'x';
 430         ++out;
 431         if (out < end)
 432                 *out = hex_asc_hi(c);
 433         ++out;
 434         if (out < end)
 435                 *out = hex_asc_lo(c);
 436         ++out;
 437
 438         *dst = out;
 439         return true;
 440 }
 441
 442 /**
 443  * string_escape_mem - quote characters in the given memory buffer
 444  * @src:        source buffer (unescaped)
 445  * @isz:        source buffer size
 446  * @dst:        destination buffer (escaped)
 447  * @osz:        destination buffer size
 448  * @flags:      combination of the flags
 449  * @only:       NULL-terminated string containing characters used to limit
 450  *              the selected escape class. If characters are included in @only
 451  *              that would not normally be escaped by the classes selected
 452  *              in @flags, they will be copied to @dst unescaped.
 453  *
 454  * Description:
 455  * The process of escaping byte buffer includes several parts. They are applied
 456  * in the following sequence.
 457  *
 458  *      1. The character is not matched to the one from @only string and thus
 459  *         must go as-is to the output.
 460  *      2. The character is matched to the printable and ASCII classes, if asked,
 461  *         and in case of match it passes through to the output.
 462  *      3. The character is matched to the printable or ASCII class, if asked,
 463  *         and in case of match it passes through to the output.
 464  *      4. The character is checked if it falls into the class given by @flags.
 465  *         %ESCAPE_OCTAL and %ESCAPE_HEX are going last since they cover any
 466  *         character. Note that they actually can't go together, otherwise
 467  *         %ESCAPE_HEX will be ignored.
 468  *
 469  * Caller must provide valid source and destination pointers. Be aware that
 470  * destination buffer will not be NULL-terminated, thus caller have to append
 471  * it if needs. The supported flags are::
 472  *
 473  *      %ESCAPE_SPACE: (special white space, not space itself)
 474  *              '\f' - form feed
 475  *              '\n' - new line
 476  *              '\r' - carriage return
 477  *              '\t' - horizontal tab
 478  *              '\v' - vertical tab
 479  *      %ESCAPE_SPECIAL:
 480  *              '\"' - double quote
 481  *              '\\' - backslash
 482  *              '\a' - alert (BEL)
 483  *              '\e' - escape
 484  *      %ESCAPE_NULL:
 485  *              '\0' - null
 486  *      %ESCAPE_OCTAL:
 487  *              '\NNN' - byte with octal value NNN (3 digits)
 488  *      %ESCAPE_ANY:
 489  *              all previous together
 490  *      %ESCAPE_NP:
 491  *              escape only non-printable characters, checked by isprint()
 492  *      %ESCAPE_ANY_NP:
 493  *              all previous together
 494  *      %ESCAPE_HEX:
 495  *              '\xHH' - byte with hexadecimal value HH (2 digits)
 496  *      %ESCAPE_NA:
 497  *              escape only non-ascii characters, checked by isascii()
 498  *      %ESCAPE_NAP:
 499  *              escape only non-printable or non-ascii characters
 500  *      %ESCAPE_APPEND:
 501  *              append characters from @only to be escaped by the given classes
 502  *
 503  * %ESCAPE_APPEND would help to pass additional characters to the escaped, when
 504  * one of %ESCAPE_NP, %ESCAPE_NA, or %ESCAPE_NAP is provided.
 505  *
 506  * One notable caveat, the %ESCAPE_NAP, %ESCAPE_NP and %ESCAPE_NA have the
 507  * higher priority than the rest of the flags (%ESCAPE_NAP is the highest).
 508  * It doesn't make much sense to use either of them without %ESCAPE_OCTAL
 509  * or %ESCAPE_HEX, because they cover most of the other character classes.
 510  * %ESCAPE_NAP can utilize %ESCAPE_SPACE or %ESCAPE_SPECIAL in addition to
 511  * the above.
 512  *
 513  * Return:
 514  * The total size of the escaped output that would be generated for
 515  * the given input and flags. To check whether the output was
 516  * truncated, compare the return value to osz. There is room left in
 517  * dst for a '\0' terminator if and only if ret < osz.
 518  */
 519 int string_escape_mem(const char *src, size_t isz, char *dst, size_t osz,
 520                       unsigned int flags, const char *only)
 521 {
 522         char *p = dst;
 523         char *end = p + osz;
 524         bool is_dict = only && *only;
 525         bool is_append = flags & ESCAPE_APPEND;
 526
 527         while (isz--) {
 528                 unsigned char c = *src++;
 529                 bool in_dict = is_dict && strchr(only, c);
 530
 531                 /*
 532                  * Apply rules in the following sequence:
 533                  *      - the @only string is supplied and does not contain a
 534                  *        character under question
 535                  *      - the character is printable and ASCII, when @flags has
 536                  *        %ESCAPE_NAP bit set
 537                  *      - the character is printable, when @flags has
 538                  *        %ESCAPE_NP bit set
 539                  *      - the character is ASCII, when @flags has
 540                  *        %ESCAPE_NA bit set
 541                  *      - the character doesn't fall into a class of symbols
 542                  *        defined by given @flags
 543                  * In these cases we just pass through a character to the
 544                  * output buffer.
 545                  *
 546                  * When %ESCAPE_APPEND is passed, the characters from @only
 547                  * have been excluded from the %ESCAPE_NAP, %ESCAPE_NP, and
 548                  * %ESCAPE_NA cases.
 549                  */
 550                 if (!(is_append || in_dict) && is_dict &&
 551                                           escape_passthrough(c, &p, end))
 552                         continue;
 553
 554                 if (!(is_append && in_dict) && isascii(c) && isprint(c) &&
 555                     flags & ESCAPE_NAP && escape_passthrough(c, &p, end))
 556                         continue;
 557
 558                 if (!(is_append && in_dict) && isprint(c) &&
 559                     flags & ESCAPE_NP && escape_passthrough(c, &p, end))
 560                         continue;
 561
 562                 if (!(is_append && in_dict) && isascii(c) &&
 563                     flags & ESCAPE_NA && escape_passthrough(c, &p, end))
 564                         continue;
 565
 566                 if (flags & ESCAPE_SPACE && escape_space(c, &p, end))
 567                         continue;
 568
 569                 if (flags & ESCAPE_SPECIAL && escape_special(c, &p, end))
 570                         continue;
 571
 572                 if (flags & ESCAPE_NULL && escape_null(c, &p, end))
 573                         continue;
 574
 575                 /* ESCAPE_OCTAL and ESCAPE_HEX always go last */
 576                 if (flags & ESCAPE_OCTAL && escape_octal(c, &p, end))
 577                         continue;
 578
 579                 if (flags & ESCAPE_HEX && escape_hex(c, &p, end))
 580                         continue;
 581
 582                 escape_passthrough(c, &p, end);
 583         }
 584
 585         return p - dst;
 586 }
 587 EXPORT_SYMBOL(string_escape_mem);
 588
 589 /*
 590  * Return an allocated string that has been escaped of special characters
 591  * and double quotes, making it safe to log in quotes.
 592  */
 593 char *kstrdup_quotable(const char *src, gfp_t gfp)
 594 {
 595         size_t slen, dlen;
 596         char *dst;
 597         const int flags = ESCAPE_HEX;
 598         const char esc[] = "\f\n\r\t\v\a\e\\\"";
 599
 600         if (!src)
 601                 return NULL;
 602         slen = strlen(src);
 603
 604         dlen = string_escape_mem(src, slen, NULL, 0, flags, esc);
 605         dst = kmalloc(dlen + 1, gfp);
 606         if (!dst)
 607                 return NULL;
 608
 609         WARN_ON(string_escape_mem(src, slen, dst, dlen, flags, esc) != dlen);
 610         dst[dlen] = '\0';
 611
 612         return dst;
 613 }
 614 EXPORT_SYMBOL_GPL(kstrdup_quotable);
 615
 616 /*
 617  * Returns allocated NULL-terminated string containing process
 618  * command line, with inter-argument NULLs replaced with spaces,
 619  * and other special characters escaped.
 620  */
 621 char *kstrdup_quotable_cmdline(struct task_struct *task, gfp_t gfp)
 622 {
 623         char *buffer, *quoted;
 624         int i, res;
 625
 626         buffer = kmalloc(PAGE_SIZE, GFP_KERNEL);
 627         if (!buffer)
 628                 return NULL;
 629
 630         res = get_cmdline(task, buffer, PAGE_SIZE - 1);
 631         buffer[res] = '\0';
 632
 633         /* Collapse trailing NULLs, leave res pointing to last non-NULL. */
 634         while (--res >= 0 && buffer[res] == '\0')
 635                 ;
 636
 637         /* Replace inter-argument NULLs. */
 638         for (i = 0; i <= res; i++)
 639                 if (buffer[i] == '\0')
 640                         buffer[i] = ' ';
 641
 642         /* Make sure result is printable. */
 643         quoted = kstrdup_quotable(buffer, gfp);
 644         kfree(buffer);
 645         return quoted;
 646 }
 647 EXPORT_SYMBOL_GPL(kstrdup_quotable_cmdline);
 648
 649 /*
 650  * Returns allocated NULL-terminated string containing pathname,
 651  * with special characters escaped, able to be safely logged. If
 652  * there is an error, the leading character will be "<".
 653  */
 654 char *kstrdup_quotable_file(struct file *file, gfp_t gfp)
 655 {
 656         char *temp, *pathname;
 657
 658         if (!file)
 659                 return kstrdup("<unknown>", gfp);
 660
 661         /* We add 11 spaces for ' (deleted)' to be appended */
 662         temp = kmalloc(PATH_MAX + 11, GFP_KERNEL);
 663         if (!temp)
 664                 return kstrdup("<no_memory>", gfp);
 665
 666         pathname = file_path(file, temp, PATH_MAX + 11);
 667         if (IS_ERR(pathname))
 668                 pathname = kstrdup("<too_long>", gfp);
 669         else
 670                 pathname = kstrdup_quotable(pathname, gfp);
 671
 672         kfree(temp);
 673         return pathname;
 674 }
 675 EXPORT_SYMBOL_GPL(kstrdup_quotable_file);
 676
 677 /**
 678  * kfree_strarray - free a number of dynamically allocated strings contained
 679  *                  in an array and the array itself
 680  *
 681  * @array: Dynamically allocated array of strings to free.
 682  * @n: Number of strings (starting from the beginning of the array) to free.
 683  *
 684  * Passing a non-NULL @array and @n == 0 as well as NULL @array are valid
 685  * use-cases. If @array is NULL, the function does nothing.
 686  */
 687 void kfree_strarray(char **array, size_t n)
 688 {
 689         unsigned int i;
 690
 691         if (!array)
 692                 return;
 693
 694         for (i = 0; i < n; i++)
 695                 kfree(array[i]);
 696         kfree(array);
 697 }
 698 EXPORT_SYMBOL_GPL(kfree_strarray);