[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 08/21] cutils: Document differences between parse_uint and qemu_st
From: |
Eric Blake |
Subject: |
[PULL 08/21] cutils: Document differences between parse_uint and qemu_strtou64 |
Date: |
Thu, 1 Jun 2023 17:02:52 -0500 |
These two functions are subtly different, and not just because of
swapped parameter order. It took me adding better unit tests to
figure out why. Document the differences to make it more obvious to
developers trying to pick which one to use, as well as to aid in
upcoming semantic changes.
While touching the documentation, adjust a mis-statement: parse_uint
does not return -EINVAL on invalid base, but assert()s, like all the
other qemu_strto* functions that take a base argument.
Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Hanna Czenczek <hreitz@redhat.com>
Message-Id: <20230522190441.64278-7-eblake@redhat.com>
---
util/cutils.c | 20 ++++++++++++--------
1 file changed, 12 insertions(+), 8 deletions(-)
diff --git a/util/cutils.c b/util/cutils.c
index 9b6ce9179c4..36c14b769fd 100644
--- a/util/cutils.c
+++ b/util/cutils.c
@@ -611,6 +611,8 @@ int qemu_strtoi64(const char *nptr, const char **endptr,
int base,
* Convert string @nptr to an uint64_t.
*
* Works like qemu_strtoul(), except it stores UINT64_MAX on overflow.
+ * (If you want to prohibit negative numbers that wrap around to
+ * positive, use parse_uint()).
*/
int qemu_strtou64(const char *nptr, const char **endptr, int base,
uint64_t *result)
@@ -721,7 +723,8 @@ const char *qemu_strchrnul(const char *s, int c)
*
* @s: String to parse
* @value: Destination for parsed integer value
- * @endptr: Destination for pointer to first character not consumed
+ * @endptr: Destination for pointer to first character not consumed, must
+ * not be %NULL
* @base: integer base, between 2 and 36 inclusive, or 0
*
* Parse unsigned integer
@@ -729,15 +732,16 @@ const char *qemu_strchrnul(const char *s, int c)
* Parsed syntax is like strtoull()'s: arbitrary whitespace, a single optional
* '+' or '-', an optional "0x" if @base is 0 or 16, one or more digits.
*
- * If @s is null, or @base is invalid, or @s doesn't start with an
- * integer in the syntax above, set *@value to 0, *@endptr to @s, and
- * return -EINVAL.
+ * If @s is null, or @s doesn't start with an integer in the syntax
+ * above, set *@value to 0, *@endptr to @s, and return -EINVAL.
*
* Set *@endptr to point right beyond the parsed integer (even if the integer
* overflows or is negative, all digits will be parsed and *@endptr will
* point right beyond them).
*
* If the integer is negative, set *@value to 0, and return -ERANGE.
+ * (If you want to allow negative numbers that wrap around within
+ * bounds, use qemu_strtou64()).
*
* If the integer overflows unsigned long long, set *@value to
* ULLONG_MAX, and return -ERANGE.
@@ -794,10 +798,10 @@ out:
*
* Parse unsigned integer from entire string
*
- * Have the same behavior of parse_uint(), but with an additional check
- * for additional data after the parsed number. If extra characters are present
- * after the parsed number, the function will return -EINVAL, and *@v will
- * be set to 0.
+ * Have the same behavior of parse_uint(), but with an additional
+ * check for additional data after the parsed number. If extra
+ * characters are present after a non-overflowing parsed number, the
+ * function will return -EINVAL, and *@v will be set to 0.
*/
int parse_uint_full(const char *s, unsigned long long *value, int base)
{
--
2.40.1
- [PULL 00/21] NBD and miscellaneous patches for 2023-06-01, Eric Blake, 2023/06/01
- [PULL 02/21] qcow2: Explicit mention of padding bytes, Eric Blake, 2023/06/01
- [PULL 05/21] test-cutils: Test integral qemu_strto* value on failures, Eric Blake, 2023/06/01
- [PULL 01/21] iotests: Fix test 104 under NBD, Eric Blake, 2023/06/01
- [PULL 08/21] cutils: Document differences between parse_uint and qemu_strtou64,
Eric Blake <=
- [PULL 10/21] cutils: Allow NULL endptr in parse_uint(), Eric Blake, 2023/06/01
- [PULL 11/21] test-cutils: Add coverage of qemu_strtod, Eric Blake, 2023/06/01
- [PULL 07/21] cutils: Fix wraparound parsing in qemu_strtoui, Eric Blake, 2023/06/01
- [PULL 09/21] cutils: Adjust signature of parse_uint[_full], Eric Blake, 2023/06/01
- [PULL 18/21] cutils: Set value in all integral qemu_strto* error paths, Eric Blake, 2023/06/01
- [PULL 16/21] test-cutils: Add more coverage to qemu_strtosz, Eric Blake, 2023/06/01