lib / string_helpers: move documentation to c-file

[sfrench/cifs-2.6.git] / lib / string_helpers.c

diff --git a/lib/string_helpers.c b/lib/string_helpers.c
index ed5c1454dd6288aacf85e4ee7db5e2e3ee947627..74ec60469640e4c0cd96752c09f8e128afc4fe8a 100644 (file)
--- a/lib/string_helpers.c
+++ b/lib/string_helpers.c
@@ -25,12 +25,15 @@
 int string_get_size(u64 size, const enum string_size_units units,
                    char *buf, int len)
 {
-       static const char *units_10[] = { "B", "kB", "MB", "GB", "TB", "PB",
-                                  "EB", "ZB", "YB", NULL};
-       static const char *units_2[] = {"B", "KiB", "MiB", "GiB", "TiB", "PiB",
-                                "EiB", "ZiB", "YiB", NULL };
-       static const char **units_str[] = {
-               [STRING_UNITS_10] =  units_10,
+       static const char *const units_10[] = {
+               "B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB", NULL
+       };
+       static const char *const units_2[] = {
+               "B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB",
+               NULL
+       };
+       static const char *const *const units_str[] = {
+               [STRING_UNITS_10] = units_10,
                [STRING_UNITS_2] = units_2,
        };
        static const unsigned int divisor[] = {
@@ -165,6 +168,44 @@ static bool unescape_special(char **src, char **dst)
        return true;
 }
 
+/**
+ * string_unescape - unquote characters in the given string
+ * @src:       source buffer (escaped)
+ * @dst:       destination buffer (unescaped)
+ * @size:      size of the destination buffer (0 to unlimit)
+ * @flags:     combination of the flags (bitwise OR):
+ *     %UNESCAPE_SPACE:
+ *             '\f' - form feed
+ *             '\n' - new line
+ *             '\r' - carriage return
+ *             '\t' - horizontal tab
+ *             '\v' - vertical tab
+ *     %UNESCAPE_OCTAL:
+ *             '\NNN' - byte with octal value NNN (1 to 3 digits)
+ *     %UNESCAPE_HEX:
+ *             '\xHH' - byte with hexadecimal value HH (1 to 2 digits)
+ *     %UNESCAPE_SPECIAL:
+ *             '\"' - double quote
+ *             '\\' - backslash
+ *             '\a' - alert (BEL)
+ *             '\e' - escape
+ *     %UNESCAPE_ANY:
+ *             all previous together
+ *
+ * Description:
+ * The function unquotes characters in the given string.
+ *
+ * Because the size of the output will be the same as or less than the size of
+ * the input, the transformation may be performed in place.
+ *
+ * Caller must provide valid source and destination pointers. Be aware that
+ * destination buffer will always be NULL-terminated. Source string must be
+ * NULL-terminated as well.
+ *
+ * Return:
+ * The amount of the characters processed to the destination buffer excluding
+ * trailing '\0' is returned.
+ */
 int string_unescape(char *src, char *dst, size_t size, unsigned int flags)
 {
        char *out = dst;