Skip to contentSkip to conversation

lib/string_helpers: clarify esc arg in string_escape_mem

PATCH In review Kees Cook 2 participants 3 messages Jul 23, 2015 – Jul 30, 2015

Subsystems (2)
lore
Share & tools
lore

Kees Cook

author
#0 lore raw

PATCH 1/1 lib/string_helpers: clarify esc arg in string_escape_mem

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

---
 lib/string_helpers.c | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
lib/string_helpers.c +6 -4
index c98ae818eb4e..0a307a97d489 100644
@@ -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
Signature · 6 lines
1.9.1


-- 
Kees Cook
Chrome OS Security
Acked-by on v1 1/1
#1 lore raw
Quoted 4 lines · 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.

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,

author
#2 lore raw
Quoted 7 lines · Rasmus Villemoes
Quoted 4 lines · 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.

Quoted 6 lines

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.

Quoted 2 lines

-Kees

Signature · 2 lines
Kees Cook
Chrome OS Security