- buffer in BUFFER, which should be freed by the caller. The string is
- read until a null character is found. If VALUE is an array with known
- length, the function will not read past the end of the array. LENGTH
- will contain the size of the string in bytes (not counting the null
- character).
-
- Assumes strings are terminated by a null character. The size of a character
- is determined by the length of the target type of the pointer or array.
- This means that a null byte present in a multi-byte character will not
- terminate the string unless the whole character is null.
-
- CHARSET is always set to the target charset. */
+ buffer in BUFFER, which should be freed by the caller. If the
+ in- and out-parameter *LENGTH is specified at -1, the string is read
+ until a null character of the appropriate width is found, otherwise
+ the string is read to the length of characters specified.
+ The size of a character is determined by the length of the target
+ type of the pointer or array. If VALUE is an array with a known
+ length, the function will not read past the end of the array.
+ On completion, *LENGTH will be set to the size of the string read in
+ characters. (If a length of -1 is specified, the length returned
+ will not include the null character). CHARSET is always set to the
+ target charset. */