lib / string_helpers: move documentation to c-file

The introduced function string_escape_mem() is a kind of opposite to string_unescape. We have several users of such functionality each of them created custom implementation. The series contains clean up of test suite, adding new call, and switching few users to use it via %*pE specifier. Test suite covers all of existing and most of potential use cases. This patch (of 11): The documentation of API belongs to c-file. This patch moves it accordingly. There is no functional change. Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> Cc: "John W . Linville" <linville@tuxdriver.com> Cc: Johannes Berg <johannes@sipsolutions.net> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Joe Perches <joe@perches.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

lib / string_helpers: move documentation to c-file
The introduced function string_escape_mem() is a kind of opposite to string_unescape. We have several users of such functionality each of them created custom implementation. The series contains clean up of test suite, adding new call, and switching few users to use it via %*pE specifier. Test suite covers all of existing and most of potential use cases. This patch (of 11): The documentation of API belongs to c-file. This patch moves it accordingly. There is no functional change. Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> Cc: "John W . Linville" <linville@tuxdriver.com> Cc: Johannes Berg <johannes@sipsolutions.net> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Joe Perches <joe@perches.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Andy Shevchenko · Linus Torvalds
1 parent 3db2e9cdc0
Showing 2 changed files with 38 additions and 34 deletions Side-by-side Diff
include/linux/string_helpers.h
lib/string_helpers.c
@@ -20,40 +20,6 @@
 #define UNESCAPE_ANY		\
 	(UNESCAPE_SPACE | UNESCAPE_OCTAL | UNESCAPE_HEX | UNESCAPE_SPECIAL)
  
-/**
- * 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
- *
- * Returns amount of characters processed to the destination buffer excluding
- * trailing '\0'.
- *
- * 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.
- */
 int string_unescape(char *src, char *dst, size_t size, unsigned int flags);
  
 static inline int string_unescape_inplace(char *buf, unsigned int flags)
@@ -168,6 +168,44 @@
 	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;
...	...	@@ -20,40 +20,6 @@
20	20	#define UNESCAPE_ANY \
21	21	(UNESCAPE_SPACE \| UNESCAPE_OCTAL \| UNESCAPE_HEX \| UNESCAPE_SPECIAL)
22	22
23		-/**
24		- * string_unescape - unquote characters in the given string
25		- * @src: source buffer (escaped)
26		- * @dst: destination buffer (unescaped)
27		- * @size: size of the destination buffer (0 to unlimit)
28		- * @flags: combination of the flags (bitwise OR):
29		- * %UNESCAPE_SPACE:
30		- * '\f' - form feed
31		- * '\n' - new line
32		- * '\r' - carriage return
33		- * '\t' - horizontal tab
34		- * '\v' - vertical tab
35		- * %UNESCAPE_OCTAL:
36		- * '\NNN' - byte with octal value NNN (1 to 3 digits)
37		- * %UNESCAPE_HEX:
38		- * '\xHH' - byte with hexadecimal value HH (1 to 2 digits)
39		- * %UNESCAPE_SPECIAL:
40		- * '\"' - double quote
41		- * '\\' - backslash
42		- * '\a' - alert (BEL)
43		- * '\e' - escape
44		- * %UNESCAPE_ANY:
45		- * all previous together
46		- *
47		- * Returns amount of characters processed to the destination buffer excluding
48		- * trailing '\0'.
49		- *
50		- * Because the size of the output will be the same as or less than the size of
51		- * the input, the transformation may be performed in place.
52		- *
53		- * Caller must provide valid source and destination pointers. Be aware that
54		- * destination buffer will always be NULL-terminated. Source string must be
55		- * NULL-terminated as well.
56		- */
57	23	int string_unescape(char src, char dst, size_t size, unsigned int flags);
58	24
59	25	static inline int string_unescape_inplace(char *buf, unsigned int flags)
...	...	@@ -168,6 +168,44 @@
168	168	return true;
169	169	}
170	170
	171	+/**
	172	+ * string_unescape - unquote characters in the given string
	173	+ * @src: source buffer (escaped)
	174	+ * @dst: destination buffer (unescaped)
	175	+ * @size: size of the destination buffer (0 to unlimit)
	176	+ * @flags: combination of the flags (bitwise OR):
	177	+ * %UNESCAPE_SPACE:
	178	+ * '\f' - form feed
	179	+ * '\n' - new line
	180	+ * '\r' - carriage return
	181	+ * '\t' - horizontal tab
	182	+ * '\v' - vertical tab
	183	+ * %UNESCAPE_OCTAL:
	184	+ * '\NNN' - byte with octal value NNN (1 to 3 digits)
	185	+ * %UNESCAPE_HEX:
	186	+ * '\xHH' - byte with hexadecimal value HH (1 to 2 digits)
	187	+ * %UNESCAPE_SPECIAL:
	188	+ * '\"' - double quote
	189	+ * '\\' - backslash
	190	+ * '\a' - alert (BEL)
	191	+ * '\e' - escape
	192	+ * %UNESCAPE_ANY:
	193	+ * all previous together
	194	+ *
	195	+ * Description:
	196	+ * The function unquotes characters in the given string.
	197	+ *
	198	+ * Because the size of the output will be the same as or less than the size of
	199	+ * the input, the transformation may be performed in place.
	200	+ *
	201	+ * Caller must provide valid source and destination pointers. Be aware that
	202	+ * destination buffer will always be NULL-terminated. Source string must be
	203	+ * NULL-terminated as well.
	204	+ *
	205	+ * Return:
	206	+ * The amount of the characters processed to the destination buffer excluding
	207	+ * trailing '\0' is returned.
	208	+ */
171	209	int string_unescape(char src, char dst, size_t size, unsigned int flags)
172	210	{
173	211	char *out = dst;