]>
git.proxmox.com Git - mirror_ubuntu-jammy-kernel.git/blob - lib/string_helpers.c
1 // SPDX-License-Identifier: GPL-2.0-only
3 * Helpers for formatting and printing strings
5 * Copyright 31 August 2008 James Bottomley
6 * Copyright (C) 2013, Intel Corporation
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>
15 #include <linux/limits.h>
17 #include <linux/slab.h>
18 #include <linux/string.h>
19 #include <linux/string_helpers.h>
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
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.
34 void string_get_size(u64 size
, u64 blk_size
, const enum string_size_units units
,
37 static const char *const units_10
[] = {
38 "B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"
40 static const char *const units_2
[] = {
41 "B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"
43 static const char *const *const units_str
[] = {
44 [STRING_UNITS_10
] = units_10
,
45 [STRING_UNITS_2
] = units_2
,
47 static const unsigned int divisor
[] = {
48 [STRING_UNITS_10
] = 1000,
49 [STRING_UNITS_2
] = 1024,
51 static const unsigned int rounding
[] = { 500, 50, 5 };
53 u32 remainder
= 0, sf_cap
;
64 /* This is Napier's algorithm. Reduce the original block size to
66 * coefficient * divisor[units]^i
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.
72 * Note: it's safe to throw away the remainders here because all the
73 * precision is in the coefficients.
75 while (blk_size
>> 32) {
76 do_div(blk_size
, divisor
[units
]);
81 do_div(size
, divisor
[units
]);
85 /* now perform the actual multiplication keeping i as the sum of the
89 /* and logarithmically reduce it until it's just under the divisor */
90 while (size
>= divisor
[units
]) {
91 remainder
= do_div(size
, divisor
[units
]);
95 /* work out in j how many digits of precision we need from the
98 for (j
= 0; sf_cap
*10 < 1000; j
++)
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 */
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) {
118 snprintf(tmp
, sizeof(tmp
), ".%03u", remainder
);
123 if (i
>= ARRAY_SIZE(units_2
))
126 unit
= units_str
[units
][i
];
128 snprintf(buf
, len
, "%u%s %s", (u32
)size
,
131 EXPORT_SYMBOL(string_get_size
);
133 static bool unescape_space(char **src
, char **dst
)
135 char *p
= *dst
, *q
= *src
;
161 static bool unescape_octal(char **src
, char **dst
)
163 char *p
= *dst
, *q
= *src
;
166 if (isodigit(*q
) == 0)
170 while (num
< 32 && isodigit(*q
) && (q
- *src
< 3)) {
180 static bool unescape_hex(char **src
, char **dst
)
182 char *p
= *dst
, *q
= *src
;
189 num
= digit
= hex_to_bin(*q
++);
193 digit
= hex_to_bin(*q
);
196 num
= (num
<< 4) | digit
;
204 static bool unescape_special(char **src
, char **dst
)
206 char *p
= *dst
, *q
= *src
;
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.
237 * The function unquotes characters in the given string.
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.
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::
249 * '\r' - carriage return
250 * '\t' - horizontal tab
251 * '\v' - vertical tab
253 * '\NNN' - byte with octal value NNN (1 to 3 digits)
255 * '\xHH' - byte with hexadecimal value HH (1 to 2 digits)
257 * '\"' - double quote
262 * all previous together
265 * The amount of the characters processed to the destination buffer excluding
266 * trailing '\0' is returned.
268 int string_unescape(char *src
, char *dst
, size_t size
, unsigned int flags
)
272 while (*src
&& --size
) {
273 if (src
[0] == '\\' && src
[1] != '\0' && size
> 1) {
277 if (flags
& UNESCAPE_SPACE
&&
278 unescape_space(&src
, &out
))
281 if (flags
& UNESCAPE_OCTAL
&&
282 unescape_octal(&src
, &out
))
285 if (flags
& UNESCAPE_HEX
&&
286 unescape_hex(&src
, &out
))
289 if (flags
& UNESCAPE_SPECIAL
&&
290 unescape_special(&src
, &out
))
301 EXPORT_SYMBOL(string_unescape
);
303 static bool escape_passthrough(unsigned char c
, char **dst
, char *end
)
313 static bool escape_space(unsigned char c
, char **dst
, char *end
)
349 static bool escape_special(unsigned char c
, char **dst
, char *end
)
382 static bool escape_null(unsigned char c
, char **dst
, char *end
)
400 static bool escape_octal(unsigned char c
, char **dst
, char *end
)
408 *out
= ((c
>> 6) & 0x07) + '0';
411 *out
= ((c
>> 3) & 0x07) + '0';
414 *out
= ((c
>> 0) & 0x07) + '0';
421 static bool escape_hex(unsigned char c
, char **dst
, char *end
)
432 *out
= hex_asc_hi(c
);
435 *out
= hex_asc_lo(c
);
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.
455 * The process of escaping byte buffer includes several parts. They are applied
456 * in the following sequence.
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.
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::
473 * %ESCAPE_SPACE: (special white space, not space itself)
476 * '\r' - carriage return
477 * '\t' - horizontal tab
478 * '\v' - vertical tab
480 * '\"' - double quote
487 * '\NNN' - byte with octal value NNN (3 digits)
489 * all previous together
491 * escape only non-printable characters, checked by isprint()
493 * all previous together
495 * '\xHH' - byte with hexadecimal value HH (2 digits)
497 * escape only non-ascii characters, checked by isascii()
499 * escape only non-printable or non-ascii characters
501 * append characters from @only to be escaped by the given classes
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.
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
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.
519 int string_escape_mem(const char *src
, size_t isz
, char *dst
, size_t osz
,
520 unsigned int flags
, const char *only
)
524 bool is_dict
= only
&& *only
;
525 bool is_append
= flags
& ESCAPE_APPEND
;
528 unsigned char c
= *src
++;
529 bool in_dict
= is_dict
&& strchr(only
, c
);
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
539 * - the character is ASCII, when @flags has
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
546 * When %ESCAPE_APPEND is passed, the characters from @only
547 * have been excluded from the %ESCAPE_NAP, %ESCAPE_NP, and
550 if (!(is_append
|| in_dict
) && is_dict
&&
551 escape_passthrough(c
, &p
, end
))
554 if (!(is_append
&& in_dict
) && isascii(c
) && isprint(c
) &&
555 flags
& ESCAPE_NAP
&& escape_passthrough(c
, &p
, end
))
558 if (!(is_append
&& in_dict
) && isprint(c
) &&
559 flags
& ESCAPE_NP
&& escape_passthrough(c
, &p
, end
))
562 if (!(is_append
&& in_dict
) && isascii(c
) &&
563 flags
& ESCAPE_NA
&& escape_passthrough(c
, &p
, end
))
566 if (flags
& ESCAPE_SPACE
&& escape_space(c
, &p
, end
))
569 if (flags
& ESCAPE_SPECIAL
&& escape_special(c
, &p
, end
))
572 if (flags
& ESCAPE_NULL
&& escape_null(c
, &p
, end
))
575 /* ESCAPE_OCTAL and ESCAPE_HEX always go last */
576 if (flags
& ESCAPE_OCTAL
&& escape_octal(c
, &p
, end
))
579 if (flags
& ESCAPE_HEX
&& escape_hex(c
, &p
, end
))
582 escape_passthrough(c
, &p
, end
);
587 EXPORT_SYMBOL(string_escape_mem
);
590 * Return an allocated string that has been escaped of special characters
591 * and double quotes, making it safe to log in quotes.
593 char *kstrdup_quotable(const char *src
, gfp_t gfp
)
597 const int flags
= ESCAPE_HEX
;
598 const char esc
[] = "\f\n\r\t\v\a\e\\\"";
604 dlen
= string_escape_mem(src
, slen
, NULL
, 0, flags
, esc
);
605 dst
= kmalloc(dlen
+ 1, gfp
);
609 WARN_ON(string_escape_mem(src
, slen
, dst
, dlen
, flags
, esc
) != dlen
);
614 EXPORT_SYMBOL_GPL(kstrdup_quotable
);
617 * Returns allocated NULL-terminated string containing process
618 * command line, with inter-argument NULLs replaced with spaces,
619 * and other special characters escaped.
621 char *kstrdup_quotable_cmdline(struct task_struct
*task
, gfp_t gfp
)
623 char *buffer
, *quoted
;
626 buffer
= kmalloc(PAGE_SIZE
, GFP_KERNEL
);
630 res
= get_cmdline(task
, buffer
, PAGE_SIZE
- 1);
633 /* Collapse trailing NULLs, leave res pointing to last non-NULL. */
634 while (--res
>= 0 && buffer
[res
] == '\0')
637 /* Replace inter-argument NULLs. */
638 for (i
= 0; i
<= res
; i
++)
639 if (buffer
[i
] == '\0')
642 /* Make sure result is printable. */
643 quoted
= kstrdup_quotable(buffer
, gfp
);
647 EXPORT_SYMBOL_GPL(kstrdup_quotable_cmdline
);
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 "<".
654 char *kstrdup_quotable_file(struct file
*file
, gfp_t gfp
)
656 char *temp
, *pathname
;
659 return kstrdup("<unknown>", gfp
);
661 /* We add 11 spaces for ' (deleted)' to be appended */
662 temp
= kmalloc(PATH_MAX
+ 11, GFP_KERNEL
);
664 return kstrdup("<no_memory>", gfp
);
666 pathname
= file_path(file
, temp
, PATH_MAX
+ 11);
667 if (IS_ERR(pathname
))
668 pathname
= kstrdup("<too_long>", gfp
);
670 pathname
= kstrdup_quotable(pathname
, gfp
);
675 EXPORT_SYMBOL_GPL(kstrdup_quotable_file
);
678 * kfree_strarray - free a number of dynamically allocated strings contained
679 * in an array and the array itself
681 * @array: Dynamically allocated array of strings to free.
682 * @n: Number of strings (starting from the beginning of the array) to free.
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.
687 void kfree_strarray(char **array
, size_t n
)
694 for (i
= 0; i
< n
; i
++)
698 EXPORT_SYMBOL_GPL(kfree_strarray
);
701 * memcpy_and_pad - Copy one buffer to another with padding
702 * @dest: Where to copy to
703 * @dest_len: The destination buffer size
704 * @src: Where to copy from
705 * @count: The number of bytes to copy
706 * @pad: Character to use for padding if space is left in destination.
708 void memcpy_and_pad(void *dest
, size_t dest_len
, const void *src
, size_t count
,
711 if (dest_len
> count
) {
712 memcpy(dest
, src
, count
);
713 memset(dest
+ count
, pad
, dest_len
- count
);
715 memcpy(dest
, src
, dest_len
);
718 EXPORT_SYMBOL(memcpy_and_pad
);