[PATCH] lib/string_helpers: clarify esc arg in string_escape_mem

[PATCH] lib/string_helpers: clarify esc arg in string_escape_mem

[Kees Cook]

The esc argument is used to reduce which characters will be escaped.
For example, using " " with ESCAPE_SPACE will not produce any escaped
spaces.

Signed-off-by: Kees Cook <keescook@chromium.org>
---
 lib/string_helpers.c | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/lib/string_helpers.c b/lib/string_helpers.c
index c98ae818eb4e..0a307a97d489 100644
--- a/lib/string_helpers.c
+++ b/lib/string_helpers.c
@@ -410,7 +410,7 @@ static bool escape_hex(unsigned char c, char **dst, char *end)
  * @dst:	destination buffer (escaped)
  * @osz:	destination buffer size
  * @flags:	combination of the flags (bitwise OR):
- *	%ESCAPE_SPACE:
+ *	%ESCAPE_SPACE: (special white space, not space itself)
  *		'\f' - form feed
  *		'\n' - new line
  *		'\r' - carriage return
@@ -432,8 +432,10 @@ static bool escape_hex(unsigned char c, char **dst, char *end)
  *		all previous together
  *	%ESCAPE_HEX:
  *		'\xHH' - byte with hexadecimal value HH (2 digits)
- * @esc:	NULL-terminated string of characters any of which, if found in
- *		the source, has to be escaped
+ * @esc:	NULL-terminated string containing characters used to limit
+ *		the selected escape class. If characters are included in @esc
+ *		that would not normally be escaped by the classes selected
+ *		in @flags, they will be copied to @dst unescaped.
  *
  * Description:
  * The process of escaping byte buffer includes several parts. They are applied
@@ -441,7 +443,7 @@ static bool escape_hex(unsigned char c, char **dst, char *end)
  *	1. The character is matched to the printable class, if asked, and in
  *	   case of match it passes through to the output.
  *	2. The character is not matched to the one from @esc string and thus
- *	   must go as is to the output.
+ *	   must go as-is to the output.
  *	3. The character is checked if it falls into the class given by @flags.
  *	   %ESCAPE_OCTAL and %ESCAPE_HEX are going last since they cover any
  *	   character. Note that they actually can't go together, otherwise
-- 
1.9.1


-- 
Kees Cook
Chrome OS Security

Re: [PATCH] lib/string_helpers: clarify esc arg in string_escape_mem

[Rasmus Villemoes]

On Fri, Jul 24 2015, Kees Cook <keescook@chromium.org> wrote:

> The esc argument is used to reduce which characters will be escaped.
> For example, using " " with ESCAPE_SPACE will not produce any escaped
> spaces.
>

Yeah, I've been confused by this more than once - the old description
and the parameter name suggest that the esc string contains additional
characters to escape, not the other way around.

Could we also rename the parameter 'only' or something like that? In any
case,

Acked-by: Rasmus Villemoes <linux@rasmusvillemoes.dk>

Re: [PATCH] lib/string_helpers: clarify esc arg in string_escape_mem

[Kees Cook]

On Thu, Jul 30, 2015 at 12:52 PM, Rasmus Villemoes
<linux@rasmusvillemoes.dk> wrote:
> On Fri, Jul 24 2015, Kees Cook <keescook@chromium.org> wrote:
>
>> The esc argument is used to reduce which characters will be escaped.
>> For example, using " " with ESCAPE_SPACE will not produce any escaped
>> spaces.
>>
>
> Yeah, I've been confused by this more than once - the old description
> and the parameter name suggest that the esc string contains additional
> characters to escape, not the other way around.
>
> Could we also rename the parameter 'only' or something like that? In any
> case,

Oh! Yeah, good idea. That would help clarify it even more. I'll send this.

>
> Acked-by: Rasmus Villemoes <linux@rasmusvillemoes.dk>

-Kees

-- 
Kees Cook
Chrome OS Security