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         default:
 365                 return false;
 366         }
 367
 368         if (out < end)
 369                 *out = '\\';
 370         ++out;
 371         if (out < end)
 372                 *out = to;
 373         ++out;
 374
 375         *dst = out;
 376         return true;
 377 }
 378
 379 static bool escape_null(unsigned char c, char **dst, char *end)
 380 {
 381         char *out = *dst;
 382
 383         if (c)
 384                 return false;
 385
 386         if (out < end)
 387                 *out = '\\';
 388         ++out;
 389         if (out < end)
 390                 *out = '0';
 391         ++out;
 392
 393         *dst = out;
 394         return true;
 395 }
 396
 397 static bool escape_octal(unsigned char c, char **dst, char *end)
 398 {
 399         char *out = *dst;
 400
 401         if (out < end)
 402                 *out = '\\';
 403         ++out;
 404         if (out < end)
 405                 *out = ((c >> 6) & 0x07) + '0';
 406         ++out;
 407         if (out < end)
 408                 *out = ((c >> 3) & 0x07) + '0';
 409         ++out;
 410         if (out < end)
 411                 *out = ((c >> 0) & 0x07) + '0';
 412         ++out;
 413
 414         *dst = out;
 415         return true;
 416 }
 417
 418 static bool escape_hex(unsigned char c, char **dst, char *end)
 419 {
 420         char *out = *dst;
 421
 422         if (out < end)
 423                 *out = '\\';
 424         ++out;
 425         if (out < end)
 426                 *out = 'x';
 427         ++out;
 428         if (out < end)
 429                 *out = hex_asc_hi(c);
 430         ++out;
 431         if (out < end)
 432                 *out = hex_asc_lo(c);
 433         ++out;
 434
 435         *dst = out;
 436         return true;
 437 }
 438
 439 /**
 440  * string_escape_mem - quote characters in the given memory buffer
 441  * @src:        source buffer (unescaped)
 442  * @isz:        source buffer size
 443  * @dst:        destination buffer (escaped)
 444  * @osz:        destination buffer size
 445  * @flags:      combination of the flags
 446  * @only:       NULL-terminated string containing characters used to limit
 447  *              the selected escape class. If characters are included in @only
 448  *              that would not normally be escaped by the classes selected
 449  *              in @flags, they will be copied to @dst unescaped.
 450  *
 451  * Description:
 452  * The process of escaping byte buffer includes several parts. They are applied
 453  * in the following sequence.
 454  *
 455  *      1. The character is matched to the printable class, if asked, and in
 456  *         case of match it passes through to the output.
 457  *      2. The character is not matched to the one from @only string and thus
 458  *         must go as-is to the output.
 459  *      3. The character is checked if it falls into the class given by @flags.
 460  *         %ESCAPE_OCTAL and %ESCAPE_HEX are going last since they cover any
 461  *         character. Note that they actually can't go together, otherwise
 462  *         %ESCAPE_HEX will be ignored.
 463  *
 464  * Caller must provide valid source and destination pointers. Be aware that
 465  * destination buffer will not be NULL-terminated, thus caller have to append
 466  * it if needs.   The supported flags are::
 467  *
 468  *      %ESCAPE_SPACE: (special white space, not space itself)
 469  *              '\f' - form feed
 470  *              '\n' - new line
 471  *              '\r' - carriage return
 472  *              '\t' - horizontal tab
 473  *              '\v' - vertical tab
 474  *      %ESCAPE_SPECIAL:
 475  *              '\\' - backslash
 476  *              '\a' - alert (BEL)
 477  *              '\e' - escape
 478  *      %ESCAPE_NULL:
 479  *              '\0' - null
 480  *      %ESCAPE_OCTAL:
 481  *              '\NNN' - byte with octal value NNN (3 digits)
 482  *      %ESCAPE_ANY:
 483  *              all previous together
 484  *      %ESCAPE_NP:
 485  *              escape only non-printable characters (checked by isprint)
 486  *      %ESCAPE_ANY_NP:
 487  *              all previous together
 488  *      %ESCAPE_HEX:
 489  *              '\xHH' - byte with hexadecimal value HH (2 digits)
 490  *
 491  * Return:
 492  * The total size of the escaped output that would be generated for
 493  * the given input and flags. To check whether the output was
 494  * truncated, compare the return value to osz. There is room left in
 495  * dst for a '\0' terminator if and only if ret < osz.
 496  */
 497 int string_escape_mem(const char *src, size_t isz, char *dst, size_t osz,
 498                       unsigned int flags, const char *only)
 499 {
 500         char *p = dst;
 501         char *end = p + osz;
 502         bool is_dict = only && *only;
 503
 504         while (isz--) {
 505                 unsigned char c = *src++;
 506
 507                 /*
 508                  * Apply rules in the following sequence:
 509                  *      - the character is printable, when @flags has
 510                  *        %ESCAPE_NP bit set
 511                  *      - the @only string is supplied and does not contain a
 512                  *        character under question
 513                  *      - the character doesn't fall into a class of symbols
 514                  *        defined by given @flags
 515                  * In these cases we just pass through a character to the
 516                  * output buffer.
 517                  */
 518                 if ((flags & ESCAPE_NP && isprint(c)) ||
 519                     (is_dict && !strchr(only, c))) {
 520                         /* do nothing */
 521                 } else {
 522                         if (flags & ESCAPE_SPACE && escape_space(c, &p, end))
 523                                 continue;
 524
 525                         if (flags & ESCAPE_SPECIAL && escape_special(c, &p, end))
 526                                 continue;
 527
 528                         if (flags & ESCAPE_NULL && escape_null(c, &p, end))
 529                                 continue;
 530
 531                         /* ESCAPE_OCTAL and ESCAPE_HEX always go last */
 532                         if (flags & ESCAPE_OCTAL && escape_octal(c, &p, end))
 533                                 continue;
 534
 535                         if (flags & ESCAPE_HEX && escape_hex(c, &p, end))
 536                                 continue;
 537                 }
 538
 539                 escape_passthrough(c, &p, end);
 540         }
 541
 542         return p - dst;
 543 }
 544 EXPORT_SYMBOL(string_escape_mem);
 545
 546 int string_escape_mem_ascii(const char *src, size_t isz, char *dst,
 547                                         size_t osz)
 548 {
 549         char *p = dst;
 550         char *end = p + osz;
 551
 552         while (isz--) {
 553                 unsigned char c = *src++;
 554
 555                 if (!isprint(c) || !isascii(c) || c == '"' || c == '\\')
 556                         escape_hex(c, &p, end);
 557                 else
 558                         escape_passthrough(c, &p, end);
 559         }
 560
 561         return p - dst;
 562 }
 563 EXPORT_SYMBOL(string_escape_mem_ascii);
 564
 565 /*
 566  * Return an allocated string that has been escaped of special characters
 567  * and double quotes, making it safe to log in quotes.
 568  */
 569 char *kstrdup_quotable(const char *src, gfp_t gfp)
 570 {
 571         size_t slen, dlen;
 572         char *dst;
 573         const int flags = ESCAPE_HEX;
 574         const char esc[] = "\f\n\r\t\v\a\e\\\"";
 575
 576         if (!src)
 577                 return NULL;
 578         slen = strlen(src);
 579
 580         dlen = string_escape_mem(src, slen, NULL, 0, flags, esc);
 581         dst = kmalloc(dlen + 1, gfp);
 582         if (!dst)
 583                 return NULL;
 584
 585         WARN_ON(string_escape_mem(src, slen, dst, dlen, flags, esc) != dlen);
 586         dst[dlen] = '\0';
 587
 588         return dst;
 589 }
 590 EXPORT_SYMBOL_GPL(kstrdup_quotable);
 591
 592 /*
 593  * Returns allocated NULL-terminated string containing process
 594  * command line, with inter-argument NULLs replaced with spaces,
 595  * and other special characters escaped.
 596  */
 597 char *kstrdup_quotable_cmdline(struct task_struct *task, gfp_t gfp)
 598 {
 599         char *buffer, *quoted;
 600         int i, res;
 601
 602         buffer = kmalloc(PAGE_SIZE, GFP_KERNEL);
 603         if (!buffer)
 604                 return NULL;
 605
 606         res = get_cmdline(task, buffer, PAGE_SIZE - 1);
 607         buffer[res] = '\0';
 608
 609         /* Collapse trailing NULLs, leave res pointing to last non-NULL. */
 610         while (--res >= 0 && buffer[res] == '\0')
 611                 ;
 612
 613         /* Replace inter-argument NULLs. */
 614         for (i = 0; i <= res; i++)
 615                 if (buffer[i] == '\0')
 616                         buffer[i] = ' ';
 617
 618         /* Make sure result is printable. */
 619         quoted = kstrdup_quotable(buffer, gfp);
 620         kfree(buffer);
 621         return quoted;
 622 }
 623 EXPORT_SYMBOL_GPL(kstrdup_quotable_cmdline);
 624
 625 /*
 626  * Returns allocated NULL-terminated string containing pathname,
 627  * with special characters escaped, able to be safely logged. If
 628  * there is an error, the leading character will be "<".
 629  */
 630 char *kstrdup_quotable_file(struct file *file, gfp_t gfp)
 631 {
 632         char *temp, *pathname;
 633
 634         if (!file)
 635                 return kstrdup("<unknown>", gfp);
 636
 637         /* We add 11 spaces for ' (deleted)' to be appended */
 638         temp = kmalloc(PATH_MAX + 11, GFP_KERNEL);
 639         if (!temp)
 640                 return kstrdup("<no_memory>", gfp);
 641
 642         pathname = file_path(file, temp, PATH_MAX + 11);
 643         if (IS_ERR(pathname))
 644                 pathname = kstrdup("<too_long>", gfp);
 645         else
 646                 pathname = kstrdup_quotable(pathname, gfp);
 647
 648         kfree(temp);
 649         return pathname;
 650 }
 651 EXPORT_SYMBOL_GPL(kstrdup_quotable_file);
 652
 653 /**
 654  * kfree_strarray - free a number of dynamically allocated strings contained
 655  *                  in an array and the array itself
 656  *
 657  * @array: Dynamically allocated array of strings to free.
 658  * @n: Number of strings (starting from the beginning of the array) to free.
 659  *
 660  * Passing a non-NULL @array and @n == 0 as well as NULL @array are valid
 661  * use-cases. If @array is NULL, the function does nothing.
 662  */
 663 void kfree_strarray(char **array, size_t n)
 664 {
 665         unsigned int i;
 666
 667         if (!array)
 668                 return;
 669
 670         for (i = 0; i < n; i++)
 671                 kfree(array[i]);
 672         kfree(array);
 673 }
 674 EXPORT_SYMBOL_GPL(kfree_strarray);