]>
git.ipfire.org Git - thirdparty/linux.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/device.h>
14 #include <linux/errno.h>
16 #include <linux/limits.h>
18 #include <linux/slab.h>
19 #include <linux/string.h>
20 #include <linux/string_helpers.h>
23 * string_get_size - get the size in the specified units
24 * @size: The size to be converted in blocks
25 * @blk_size: Size of the block (use 1 for size in bytes)
26 * @units: units to use (powers of 1000 or 1024)
27 * @buf: buffer to format to
28 * @len: length of buffer
30 * This function returns a string formatted to 3 significant figures
31 * giving the size in the required units. @buf should have room for
32 * at least 9 bytes and will always be zero terminated.
34 * Return value: number of characters of output that would have been written
35 * (which may be greater than len, if output was truncated).
37 int string_get_size(u64 size
, u64 blk_size
, const enum string_size_units units
,
40 static const char *const units_10
[] = {
41 "B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"
43 static const char *const units_2
[] = {
44 "B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"
46 static const char *const *const units_str
[] = {
47 [STRING_UNITS_10
] = units_10
,
48 [STRING_UNITS_2
] = units_2
,
50 static const unsigned int divisor
[] = {
51 [STRING_UNITS_10
] = 1000,
52 [STRING_UNITS_2
] = 1024,
54 static const unsigned int rounding
[] = { 500, 50, 5 };
56 u32 remainder
= 0, sf_cap
;
67 /* This is Napier's algorithm. Reduce the original block size to
69 * coefficient * divisor[units]^i
71 * we do the reduction so both coefficients are just under 32 bits so
72 * that multiplying them together won't overflow 64 bits and we keep
73 * as much precision as possible in the numbers.
75 * Note: it's safe to throw away the remainders here because all the
76 * precision is in the coefficients.
78 while (blk_size
>> 32) {
79 do_div(blk_size
, divisor
[units
]);
84 do_div(size
, divisor
[units
]);
88 /* now perform the actual multiplication keeping i as the sum of the
92 /* and logarithmically reduce it until it's just under the divisor */
93 while (size
>= divisor
[units
]) {
94 remainder
= do_div(size
, divisor
[units
]);
98 /* work out in j how many digits of precision we need from the
101 for (j
= 0; sf_cap
*10 < 1000; j
++)
104 if (units
== STRING_UNITS_2
) {
105 /* express the remainder as a decimal. It's currently the
106 * numerator of a fraction whose denominator is
107 * divisor[units], which is 1 << 10 for STRING_UNITS_2 */
112 /* add a 5 to the digit below what will be printed to ensure
113 * an arithmetical round up and carry it through to size */
114 remainder
+= rounding
[j
];
115 if (remainder
>= 1000) {
121 snprintf(tmp
, sizeof(tmp
), ".%03u", remainder
);
126 if (i
>= ARRAY_SIZE(units_2
))
129 unit
= units_str
[units
][i
];
131 return snprintf(buf
, len
, "%u%s %s", (u32
)size
,
134 EXPORT_SYMBOL(string_get_size
);
137 * parse_int_array_user - Split string into a sequence of integers
138 * @from: The user space buffer to read from
139 * @count: The maximum number of bytes to read
140 * @array: Returned pointer to sequence of integers
142 * On success @array is allocated and initialized with a sequence of
143 * integers extracted from the @from plus an additional element that
144 * begins the sequence and specifies the integers count.
146 * Caller takes responsibility for freeing @array when it is no longer
149 int parse_int_array_user(const char __user
*from
, size_t count
, int **array
)
155 buf
= memdup_user_nul(from
, count
);
159 get_options(buf
, 0, &nints
);
165 ints
= kcalloc(nints
+ 1, sizeof(*ints
), GFP_KERNEL
);
171 get_options(buf
, nints
+ 1, ints
);
178 EXPORT_SYMBOL(parse_int_array_user
);
180 static bool unescape_space(char **src
, char **dst
)
182 char *p
= *dst
, *q
= *src
;
208 static bool unescape_octal(char **src
, char **dst
)
210 char *p
= *dst
, *q
= *src
;
213 if (isodigit(*q
) == 0)
217 while (num
< 32 && isodigit(*q
) && (q
- *src
< 3)) {
227 static bool unescape_hex(char **src
, char **dst
)
229 char *p
= *dst
, *q
= *src
;
236 num
= digit
= hex_to_bin(*q
++);
240 digit
= hex_to_bin(*q
);
243 num
= (num
<< 4) | digit
;
251 static bool unescape_special(char **src
, char **dst
)
253 char *p
= *dst
, *q
= *src
;
277 * string_unescape - unquote characters in the given string
278 * @src: source buffer (escaped)
279 * @dst: destination buffer (unescaped)
280 * @size: size of the destination buffer (0 to unlimit)
281 * @flags: combination of the flags.
284 * The function unquotes characters in the given string.
286 * Because the size of the output will be the same as or less than the size of
287 * the input, the transformation may be performed in place.
289 * Caller must provide valid source and destination pointers. Be aware that
290 * destination buffer will always be NULL-terminated. Source string must be
291 * NULL-terminated as well. The supported flags are::
296 * '\r' - carriage return
297 * '\t' - horizontal tab
298 * '\v' - vertical tab
300 * '\NNN' - byte with octal value NNN (1 to 3 digits)
302 * '\xHH' - byte with hexadecimal value HH (1 to 2 digits)
304 * '\"' - double quote
309 * all previous together
312 * The amount of the characters processed to the destination buffer excluding
313 * trailing '\0' is returned.
315 int string_unescape(char *src
, char *dst
, size_t size
, unsigned int flags
)
319 while (*src
&& --size
) {
320 if (src
[0] == '\\' && src
[1] != '\0' && size
> 1) {
324 if (flags
& UNESCAPE_SPACE
&&
325 unescape_space(&src
, &out
))
328 if (flags
& UNESCAPE_OCTAL
&&
329 unescape_octal(&src
, &out
))
332 if (flags
& UNESCAPE_HEX
&&
333 unescape_hex(&src
, &out
))
336 if (flags
& UNESCAPE_SPECIAL
&&
337 unescape_special(&src
, &out
))
348 EXPORT_SYMBOL(string_unescape
);
350 static bool escape_passthrough(unsigned char c
, char **dst
, char *end
)
360 static bool escape_space(unsigned char c
, char **dst
, char *end
)
396 static bool escape_special(unsigned char c
, char **dst
, char *end
)
429 static bool escape_null(unsigned char c
, char **dst
, char *end
)
447 static bool escape_octal(unsigned char c
, char **dst
, char *end
)
455 *out
= ((c
>> 6) & 0x07) + '0';
458 *out
= ((c
>> 3) & 0x07) + '0';
461 *out
= ((c
>> 0) & 0x07) + '0';
468 static bool escape_hex(unsigned char c
, char **dst
, char *end
)
479 *out
= hex_asc_hi(c
);
482 *out
= hex_asc_lo(c
);
490 * string_escape_mem - quote characters in the given memory buffer
491 * @src: source buffer (unescaped)
492 * @isz: source buffer size
493 * @dst: destination buffer (escaped)
494 * @osz: destination buffer size
495 * @flags: combination of the flags
496 * @only: NULL-terminated string containing characters used to limit
497 * the selected escape class. If characters are included in @only
498 * that would not normally be escaped by the classes selected
499 * in @flags, they will be copied to @dst unescaped.
502 * The process of escaping byte buffer includes several parts. They are applied
503 * in the following sequence.
505 * 1. The character is not matched to the one from @only string and thus
506 * must go as-is to the output.
507 * 2. The character is matched to the printable and ASCII classes, if asked,
508 * and in case of match it passes through to the output.
509 * 3. The character is matched to the printable or ASCII class, if asked,
510 * and in case of match it passes through to the output.
511 * 4. The character is checked if it falls into the class given by @flags.
512 * %ESCAPE_OCTAL and %ESCAPE_HEX are going last since they cover any
513 * character. Note that they actually can't go together, otherwise
514 * %ESCAPE_HEX will be ignored.
516 * Caller must provide valid source and destination pointers. Be aware that
517 * destination buffer will not be NULL-terminated, thus caller have to append
518 * it if needs. The supported flags are::
520 * %ESCAPE_SPACE: (special white space, not space itself)
523 * '\r' - carriage return
524 * '\t' - horizontal tab
525 * '\v' - vertical tab
527 * '\"' - double quote
534 * '\NNN' - byte with octal value NNN (3 digits)
536 * all previous together
538 * escape only non-printable characters, checked by isprint()
540 * all previous together
542 * '\xHH' - byte with hexadecimal value HH (2 digits)
544 * escape only non-ascii characters, checked by isascii()
546 * escape only non-printable or non-ascii characters
548 * append characters from @only to be escaped by the given classes
550 * %ESCAPE_APPEND would help to pass additional characters to the escaped, when
551 * one of %ESCAPE_NP, %ESCAPE_NA, or %ESCAPE_NAP is provided.
553 * One notable caveat, the %ESCAPE_NAP, %ESCAPE_NP and %ESCAPE_NA have the
554 * higher priority than the rest of the flags (%ESCAPE_NAP is the highest).
555 * It doesn't make much sense to use either of them without %ESCAPE_OCTAL
556 * or %ESCAPE_HEX, because they cover most of the other character classes.
557 * %ESCAPE_NAP can utilize %ESCAPE_SPACE or %ESCAPE_SPECIAL in addition to
561 * The total size of the escaped output that would be generated for
562 * the given input and flags. To check whether the output was
563 * truncated, compare the return value to osz. There is room left in
564 * dst for a '\0' terminator if and only if ret < osz.
566 int string_escape_mem(const char *src
, size_t isz
, char *dst
, size_t osz
,
567 unsigned int flags
, const char *only
)
571 bool is_dict
= only
&& *only
;
572 bool is_append
= flags
& ESCAPE_APPEND
;
575 unsigned char c
= *src
++;
576 bool in_dict
= is_dict
&& strchr(only
, c
);
579 * Apply rules in the following sequence:
580 * - the @only string is supplied and does not contain a
581 * character under question
582 * - the character is printable and ASCII, when @flags has
583 * %ESCAPE_NAP bit set
584 * - the character is printable, when @flags has
586 * - the character is ASCII, when @flags has
588 * - the character doesn't fall into a class of symbols
589 * defined by given @flags
590 * In these cases we just pass through a character to the
593 * When %ESCAPE_APPEND is passed, the characters from @only
594 * have been excluded from the %ESCAPE_NAP, %ESCAPE_NP, and
597 if (!(is_append
|| in_dict
) && is_dict
&&
598 escape_passthrough(c
, &p
, end
))
601 if (!(is_append
&& in_dict
) && isascii(c
) && isprint(c
) &&
602 flags
& ESCAPE_NAP
&& escape_passthrough(c
, &p
, end
))
605 if (!(is_append
&& in_dict
) && isprint(c
) &&
606 flags
& ESCAPE_NP
&& escape_passthrough(c
, &p
, end
))
609 if (!(is_append
&& in_dict
) && isascii(c
) &&
610 flags
& ESCAPE_NA
&& escape_passthrough(c
, &p
, end
))
613 if (flags
& ESCAPE_SPACE
&& escape_space(c
, &p
, end
))
616 if (flags
& ESCAPE_SPECIAL
&& escape_special(c
, &p
, end
))
619 if (flags
& ESCAPE_NULL
&& escape_null(c
, &p
, end
))
622 /* ESCAPE_OCTAL and ESCAPE_HEX always go last */
623 if (flags
& ESCAPE_OCTAL
&& escape_octal(c
, &p
, end
))
626 if (flags
& ESCAPE_HEX
&& escape_hex(c
, &p
, end
))
629 escape_passthrough(c
, &p
, end
);
634 EXPORT_SYMBOL(string_escape_mem
);
637 * Return an allocated string that has been escaped of special characters
638 * and double quotes, making it safe to log in quotes.
640 char *kstrdup_quotable(const char *src
, gfp_t gfp
)
644 const int flags
= ESCAPE_HEX
;
645 const char esc
[] = "\f\n\r\t\v\a\e\\\"";
651 dlen
= string_escape_mem(src
, slen
, NULL
, 0, flags
, esc
);
652 dst
= kmalloc(dlen
+ 1, gfp
);
656 WARN_ON(string_escape_mem(src
, slen
, dst
, dlen
, flags
, esc
) != dlen
);
661 EXPORT_SYMBOL_GPL(kstrdup_quotable
);
664 * Returns allocated NULL-terminated string containing process
665 * command line, with inter-argument NULLs replaced with spaces,
666 * and other special characters escaped.
668 char *kstrdup_quotable_cmdline(struct task_struct
*task
, gfp_t gfp
)
670 char *buffer
, *quoted
;
673 buffer
= kmalloc(PAGE_SIZE
, GFP_KERNEL
);
677 res
= get_cmdline(task
, buffer
, PAGE_SIZE
- 1);
680 /* Collapse trailing NULLs, leave res pointing to last non-NULL. */
681 while (--res
>= 0 && buffer
[res
] == '\0')
684 /* Replace inter-argument NULLs. */
685 for (i
= 0; i
<= res
; i
++)
686 if (buffer
[i
] == '\0')
689 /* Make sure result is printable. */
690 quoted
= kstrdup_quotable(buffer
, gfp
);
694 EXPORT_SYMBOL_GPL(kstrdup_quotable_cmdline
);
697 * Returns allocated NULL-terminated string containing pathname,
698 * with special characters escaped, able to be safely logged. If
699 * there is an error, the leading character will be "<".
701 char *kstrdup_quotable_file(struct file
*file
, gfp_t gfp
)
703 char *temp
, *pathname
;
706 return kstrdup("<unknown>", gfp
);
708 /* We add 11 spaces for ' (deleted)' to be appended */
709 temp
= kmalloc(PATH_MAX
+ 11, GFP_KERNEL
);
711 return kstrdup("<no_memory>", gfp
);
713 pathname
= file_path(file
, temp
, PATH_MAX
+ 11);
714 if (IS_ERR(pathname
))
715 pathname
= kstrdup("<too_long>", gfp
);
717 pathname
= kstrdup_quotable(pathname
, gfp
);
722 EXPORT_SYMBOL_GPL(kstrdup_quotable_file
);
725 * Returns duplicate string in which the @old characters are replaced by @new.
727 char *kstrdup_and_replace(const char *src
, char old
, char new, gfp_t gfp
)
731 dst
= kstrdup(src
, gfp
);
735 return strreplace(dst
, old
, new);
737 EXPORT_SYMBOL_GPL(kstrdup_and_replace
);
740 * kasprintf_strarray - allocate and fill array of sequential strings
741 * @gfp: flags for the slab allocator
742 * @prefix: prefix to be used
743 * @n: amount of lines to be allocated and filled
745 * Allocates and fills @n strings using pattern "%s-%zu", where prefix
746 * is provided by caller. The caller is responsible to free them with
747 * kfree_strarray() after use.
749 * Returns array of strings or NULL when memory can't be allocated.
751 char **kasprintf_strarray(gfp_t gfp
, const char *prefix
, size_t n
)
756 names
= kcalloc(n
+ 1, sizeof(char *), gfp
);
760 for (i
= 0; i
< n
; i
++) {
761 names
[i
] = kasprintf(gfp
, "%s-%zu", prefix
, i
);
763 kfree_strarray(names
, i
);
770 EXPORT_SYMBOL_GPL(kasprintf_strarray
);
773 * kfree_strarray - free a number of dynamically allocated strings contained
774 * in an array and the array itself
776 * @array: Dynamically allocated array of strings to free.
777 * @n: Number of strings (starting from the beginning of the array) to free.
779 * Passing a non-NULL @array and @n == 0 as well as NULL @array are valid
780 * use-cases. If @array is NULL, the function does nothing.
782 void kfree_strarray(char **array
, size_t n
)
789 for (i
= 0; i
< n
; i
++)
793 EXPORT_SYMBOL_GPL(kfree_strarray
);
800 static void devm_kfree_strarray(struct device
*dev
, void *res
)
802 struct strarray
*array
= res
;
804 kfree_strarray(array
->array
, array
->n
);
807 char **devm_kasprintf_strarray(struct device
*dev
, const char *prefix
, size_t n
)
809 struct strarray
*ptr
;
811 ptr
= devres_alloc(devm_kfree_strarray
, sizeof(*ptr
), GFP_KERNEL
);
813 return ERR_PTR(-ENOMEM
);
815 ptr
->array
= kasprintf_strarray(GFP_KERNEL
, prefix
, n
);
818 return ERR_PTR(-ENOMEM
);
822 devres_add(dev
, ptr
);
826 EXPORT_SYMBOL_GPL(devm_kasprintf_strarray
);
829 * strscpy_pad() - Copy a C-string into a sized buffer
830 * @dest: Where to copy the string to
831 * @src: Where to copy the string from
832 * @count: Size of destination buffer
834 * Copy the string, or as much of it as fits, into the dest buffer. The
835 * behavior is undefined if the string buffers overlap. The destination
836 * buffer is always %NUL terminated, unless it's zero-sized.
838 * If the source string is shorter than the destination buffer, zeros
839 * the tail of the destination buffer.
841 * For full explanation of why you may want to consider using the
842 * 'strscpy' functions please see the function docstring for strscpy().
845 * * The number of characters copied (not including the trailing %NUL)
846 * * -E2BIG if count is 0 or @src was truncated.
848 ssize_t
strscpy_pad(char *dest
, const char *src
, size_t count
)
852 written
= strscpy(dest
, src
, count
);
853 if (written
< 0 || written
== count
- 1)
856 memset(dest
+ written
+ 1, 0, count
- written
- 1);
860 EXPORT_SYMBOL(strscpy_pad
);
863 * skip_spaces - Removes leading whitespace from @str.
864 * @str: The string to be stripped.
866 * Returns a pointer to the first non-whitespace character in @str.
868 char *skip_spaces(const char *str
)
870 while (isspace(*str
))
874 EXPORT_SYMBOL(skip_spaces
);
877 * strim - Removes leading and trailing whitespace from @s.
878 * @s: The string to be stripped.
880 * Note that the first trailing whitespace is replaced with a %NUL-terminator
881 * in the given string @s. Returns a pointer to the first non-whitespace
894 while (end
>= s
&& isspace(*end
))
898 return skip_spaces(s
);
900 EXPORT_SYMBOL(strim
);
903 * sysfs_streq - return true if strings are equal, modulo trailing newline
905 * @s2: another string
907 * This routine returns true iff two strings are equal, treating both
908 * NUL and newline-then-NUL as equivalent string terminations. It's
909 * geared for use with sysfs input strings, which generally terminate
910 * with newlines but are compared against values without newlines.
912 bool sysfs_streq(const char *s1
, const char *s2
)
914 while (*s1
&& *s1
== *s2
) {
921 if (!*s1
&& *s2
== '\n' && !s2
[1])
923 if (*s1
== '\n' && !s1
[1] && !*s2
)
927 EXPORT_SYMBOL(sysfs_streq
);
930 * match_string - matches given string in an array
931 * @array: array of strings
932 * @n: number of strings in the array or -1 for NULL terminated arrays
933 * @string: string to match with
935 * This routine will look for a string in an array of strings up to the
936 * n-th element in the array or until the first NULL element.
938 * Historically the value of -1 for @n, was used to search in arrays that
939 * are NULL terminated. However, the function does not make a distinction
940 * when finishing the search: either @n elements have been compared OR
941 * the first NULL element was found.
944 * index of a @string in the @array if matches, or %-EINVAL otherwise.
946 int match_string(const char * const *array
, size_t n
, const char *string
)
951 for (index
= 0; index
< n
; index
++) {
955 if (!strcmp(item
, string
))
961 EXPORT_SYMBOL(match_string
);
964 * __sysfs_match_string - matches given string in an array
965 * @array: array of strings
966 * @n: number of strings in the array or -1 for NULL terminated arrays
967 * @str: string to match with
969 * Returns index of @str in the @array or -EINVAL, just like match_string().
970 * Uses sysfs_streq instead of strcmp for matching.
972 * This routine will look for a string in an array of strings up to the
973 * n-th element in the array or until the first NULL element.
975 * Historically the value of -1 for @n, was used to search in arrays that
976 * are NULL terminated. However, the function does not make a distinction
977 * when finishing the search: either @n elements have been compared OR
978 * the first NULL element was found.
980 int __sysfs_match_string(const char * const *array
, size_t n
, const char *str
)
985 for (index
= 0; index
< n
; index
++) {
989 if (sysfs_streq(item
, str
))
995 EXPORT_SYMBOL(__sysfs_match_string
);
998 * strreplace - Replace all occurrences of character in string.
999 * @str: The string to operate on.
1000 * @old: The character being replaced.
1001 * @new: The character @old is replaced with.
1003 * Replaces the each @old character with a @new one in the given string @str.
1005 * Return: pointer to the string @str itself.
1007 char *strreplace(char *str
, char old
, char new)
1016 EXPORT_SYMBOL(strreplace
);
1019 * memcpy_and_pad - Copy one buffer to another with padding
1020 * @dest: Where to copy to
1021 * @dest_len: The destination buffer size
1022 * @src: Where to copy from
1023 * @count: The number of bytes to copy
1024 * @pad: Character to use for padding if space is left in destination.
1026 void memcpy_and_pad(void *dest
, size_t dest_len
, const void *src
, size_t count
,
1029 if (dest_len
> count
) {
1030 memcpy(dest
, src
, count
);
1031 memset(dest
+ count
, pad
, dest_len
- count
);
1033 memcpy(dest
, src
, dest_len
);
1036 EXPORT_SYMBOL(memcpy_and_pad
);
1038 #ifdef CONFIG_FORTIFY_SOURCE
1039 /* These are placeholders for fortify compile-time warnings. */
1040 void __read_overflow2_field(size_t avail
, size_t wanted
) { }
1041 EXPORT_SYMBOL(__read_overflow2_field
);
1042 void __write_overflow_field(size_t avail
, size_t wanted
) { }
1043 EXPORT_SYMBOL(__write_overflow_field
);
1045 void fortify_panic(const char *name
)
1047 pr_emerg("detected buffer overflow in %s\n", name
);
1050 EXPORT_SYMBOL(fortify_panic
);
1051 #endif /* CONFIG_FORTIFY_SOURCE */