[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [Qemu-trivial] [PATCH v2 3/3] util/cutils: Move functio
From: |
Laurent Vivier |
Subject: |
Re: [Qemu-devel] [Qemu-trivial] [PATCH v2 3/3] util/cutils: Move function documentations to the header |
Date: |
Wed, 30 Jan 2019 11:26:14 +0100 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.8.0 |
On 04/01/2019 19:12, Philippe Mathieu-Daudé wrote:
> Many functions have documentation before the implementation in
> cutils.c. Since we expect documentation around the prototype
> declaration in headers, move the comments in cutils.h.
>
> Signed-off-by: Philippe Mathieu-Daudé <address@hidden>
> ---
> include/qemu/cutils.h | 224 ++++++++++++++++++++++++++++++++++++++++++
> util/cutils.c | 185 ----------------------------------
> 2 files changed, 224 insertions(+), 185 deletions(-)
>
> diff --git a/include/qemu/cutils.h b/include/qemu/cutils.h
> index 644f2d75bd..f41b00ad37 100644
> --- a/include/qemu/cutils.h
> +++ b/include/qemu/cutils.h
> @@ -47,6 +47,7 @@
> * bytes and then add a NUL
> */
> void pstrcpy(char *buf, int buf_size, const char *str);
> +
> /**
> * strpadcpy:
> * @buf: buffer to copy string into
> @@ -60,6 +61,7 @@ void pstrcpy(char *buf, int buf_size, const char *str);
> * first @buf_size characters of @str, with no terminator.
> */
> void strpadcpy(char *buf, int buf_size, const char *str, char pad);
> +
> /**
> * pstrcat:
> * @buf: buffer containing existing string
> @@ -77,6 +79,7 @@ void strpadcpy(char *buf, int buf_size, const char *str,
> char pad);
> * Returns: @buf.
> */
> char *pstrcat(char *buf, int buf_size, const char *s);
> +
> /**
> * strstart:
> * @str: string to test
> @@ -94,6 +97,7 @@ char *pstrcat(char *buf, int buf_size, const char *s);
> * Returns: true if @str starts with prefix @val, false otherwise.
> */
> int strstart(const char *str, const char *val, const char **ptr);
> +
> /**
> * stristart:
> * @str: string to test
> @@ -110,6 +114,7 @@ int strstart(const char *str, const char *val, const char
> **ptr);
> * false otherwise.
> */
> int stristart(const char *str, const char *val, const char **ptr);
> +
> /**
> * qemu_strnlen:
> * @s: string
> @@ -126,6 +131,7 @@ int stristart(const char *str, const char *val, const
> char **ptr);
> * Returns: length of @s in bytes, or @max_len, whichever is smaller.
> */
> int qemu_strnlen(const char *s, int max_len);
> +
> /**
> * qemu_strsep:
> * @input: pointer to string to parse
> @@ -147,6 +153,16 @@ int qemu_strnlen(const char *s, int max_len);
> * Returns: the pointer originally in @input.
> */
> char *qemu_strsep(char **input, const char *delim);
> +
> +/**
> + * qemu_strchrnul:
> + *
> + * @s: String to parse.
> + * @c: Character to find.
> + *
> + * Searches for the first occurrence of @c in @s, and returns a pointer
> + * to the trailing null byte if none was found.
> + */
> #ifdef HAVE_STRCHRNUL
> static inline const char *qemu_strchrnul(const char *s, int c)
> {
> @@ -155,27 +171,235 @@ static inline const char *qemu_strchrnul(const char
> *s, int c)
> #else
> const char *qemu_strchrnul(const char *s, int c);
> #endif
> +
> time_t mktimegm(struct tm *tm);
> int qemu_fdatasync(int fd);
> int fcntl_setfl(int fd, int flag);
> int qemu_parse_fd(const char *param);
> +
> +/**
> + * qemu_strtoi:
> + *
> + * Convert string @nptr to an integer, and store it in @result.
> + *
> + * This is a wrapper around strtol() that is harder to misuse.
> + * Semantics of @nptr, @endptr, @base match strtol() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL. This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows @result, store INT_MAX in @result,
> + * and return -ERANGE.
> + *
> + * If the conversion underflows @result, store INT_MIN in @result,
> + * and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + */
> int qemu_strtoi(const char *nptr, const char **endptr, int base,
> int *result);
> +
> +/**
> + * qemu_strtoui:
> + *
> + * Convert string @nptr to an unsigned integer, and store it in @result.
> + *
> + * This is a wrapper around strtoul() that is harder to misuse.
> + * Semantics of @nptr, @endptr, @base match strtoul() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL. This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows @result, store UINT_MAX in @result,
> + * and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + *
> + * Note that a number with a leading minus sign gets converted without
> + * the minus sign, checked for overflow (see above), then negated (in
> + * @result's type). This is exactly how strtoul() works.
> + */
> int qemu_strtoui(const char *nptr, const char **endptr, int base,
> unsigned int *result);
> +
> +/**
> + * qemu_strtol:
> + *
> + * Convert string @nptr to a long integer, and store it in @result.
> + *
> + * This is a wrapper around strtol() that is harder to misuse.
> + * Semantics of @nptr, @endptr, @base match strtol() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL. This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows @result, store LONG_MAX in @result,
> + * and return -ERANGE.
> + *
> + * If the conversion underflows @result, store LONG_MIN in @result,
> + * and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + */
> int qemu_strtol(const char *nptr, const char **endptr, int base,
> long *result);
> +
> +/**
> + * qemu_strtoul:
> + *
> + * Convert string @nptr to an unsigned long, and store it in @result.
> + *
> + * This is a wrapper around strtoul() that is harder to misuse.
> + * Semantics of @nptr, @endptr, @base match strtoul() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL. This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows @result, store ULONG_MAX in @result,
> + * and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + *
> + * Note that a number with a leading minus sign gets converted without
> + * the minus sign, checked for overflow (see above), then negated (in
> + * @result's type). This is exactly how strtoul() works.
> + */
> +
> int qemu_strtoul(const char *nptr, const char **endptr, int base,
> unsigned long *result);
> +
> +/**
> + * qemu_strtoi64:
> + *
> + * Convert string @nptr to an int64_t.
> + *
> + * Works like qemu_strtol(), except it stores INT64_MAX on overflow,
> + * and INT_MIN on underflow.
> + */
> int qemu_strtoi64(const char *nptr, const char **endptr, int base,
> int64_t *result);
> +
> +/**
> + * qemu_strtou64:
> + *
> + * Convert string @nptr to an uint64_t.
> + *
> + * Works like qemu_strtoul(), except it stores UINT64_MAX on overflow.
> + */
> int qemu_strtou64(const char *nptr, const char **endptr, int base,
> uint64_t *result);
> +
> +/**
> + * qemu_strtod:
> + *
> + * Convert string @nptr to a double.
> + *
> + * This is a wrapper around strtod() that is harder to misuse.
> + * Semantics of @nptr and @endptr match strtod() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL. This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows, store +/-HUGE_VAL in @result, depending
> + * on the sign, and return -ERANGE.
> + *
> + * If the conversion underflows, store +/-0.0 in @result, depending on the
> + * sign, and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + */
> int qemu_strtod(const char *nptr, const char **endptr, double *result);
> +
> +/**
> + * qemu_strtod_finite:
> + *
> + * Convert string @nptr to a finite double.
> + *
> + * Works like qemu_strtod(), except that "NaN" and "inf" are rejected
> + * with -EINVAL and no conversion is performed.
> + */
> int qemu_strtod_finite(const char *nptr, const char **endptr, double
> *result);
>
> +/**
> + * parse_uint:
> + *
> + * @s: String to parse
> + * @value: Destination for parsed integer value
> + * @endptr: Destination for pointer to first character not consumed
> + * @base: integer base, between 2 and 36 inclusive, or 0
> + *
> + * Parse unsigned integer
> + *
> + * 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 address@hidden to 0, address@hidden to
> @s, and
> + * return -EINVAL.
> + *
> + * Set address@hidden to point right beyond the parsed integer (even if the
> integer
> + * overflows or is negative, all digits will be parsed and address@hidden
> will
> + * point right beyond them).
> + *
> + * If the integer is negative, set address@hidden to 0, and return -ERANGE.
> + *
> + * If the integer overflows unsigned long long, set address@hidden to
> + * ULLONG_MAX, and return -ERANGE.
> + *
> + * Else, set address@hidden to the parsed integer, and return 0.
> + */
> int parse_uint(const char *s, unsigned long long *value, char **endptr,
> int base);
> +
> +/**
> + * parse_uint_full:
> + *
> + * @s: String to parse
> + * @value: Destination for parsed integer value
> + * @base: integer base, between 2 and 36 inclusive, or 0
> + *
> + * 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
> address@hidden will
> + * be set to 0.
> + */
> int parse_uint_full(const char *s, unsigned long long *value, int base);
>
> int qemu_strtosz(const char *nptr, const char **end, uint64_t *result);
> diff --git a/util/cutils.c b/util/cutils.c
> index a8a3a3ba3b..a4c8858712 100644
> --- a/util/cutils.c
> +++ b/util/cutils.c
> @@ -296,30 +296,6 @@ static int check_strtox_error(const char *nptr, char *ep,
> return -libc_errno;
> }
>
> -/**
> - * Convert string @nptr to an integer, and store it in @result.
> - *
> - * This is a wrapper around strtol() that is harder to misuse.
> - * Semantics of @nptr, @endptr, @base match strtol() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL. This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows @result, store INT_MAX in @result,
> - * and return -ERANGE.
> - *
> - * If the conversion underflows @result, store INT_MIN in @result,
> - * and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - */
> int qemu_strtoi(const char *nptr, const char **endptr, int base,
> int *result)
> {
> @@ -348,31 +324,6 @@ int qemu_strtoi(const char *nptr, const char **endptr,
> int base,
> return check_strtox_error(nptr, ep, endptr, errno);
> }
>
> -/**
> - * Convert string @nptr to an unsigned integer, and store it in @result.
> - *
> - * This is a wrapper around strtoul() that is harder to misuse.
> - * Semantics of @nptr, @endptr, @base match strtoul() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL. This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows @result, store UINT_MAX in @result,
> - * and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - *
> - * Note that a number with a leading minus sign gets converted without
> - * the minus sign, checked for overflow (see above), then negated (in
> - * @result's type). This is exactly how strtoul() works.
> - */
> int qemu_strtoui(const char *nptr, const char **endptr, int base,
> unsigned int *result)
> {
> @@ -407,30 +358,6 @@ int qemu_strtoui(const char *nptr, const char **endptr,
> int base,
> return check_strtox_error(nptr, ep, endptr, errno);
> }
>
> -/**
> - * Convert string @nptr to a long integer, and store it in @result.
> - *
> - * This is a wrapper around strtol() that is harder to misuse.
> - * Semantics of @nptr, @endptr, @base match strtol() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL. This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows @result, store LONG_MAX in @result,
> - * and return -ERANGE.
> - *
> - * If the conversion underflows @result, store LONG_MIN in @result,
> - * and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - */
> int qemu_strtol(const char *nptr, const char **endptr, int base,
> long *result)
> {
> @@ -449,31 +376,6 @@ int qemu_strtol(const char *nptr, const char **endptr,
> int base,
> return check_strtox_error(nptr, ep, endptr, errno);
> }
>
> -/**
> - * Convert string @nptr to an unsigned long, and store it in @result.
> - *
> - * This is a wrapper around strtoul() that is harder to misuse.
> - * Semantics of @nptr, @endptr, @base match strtoul() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL. This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows @result, store ULONG_MAX in @result,
> - * and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - *
> - * Note that a number with a leading minus sign gets converted without
> - * the minus sign, checked for overflow (see above), then negated (in
> - * @result's type). This is exactly how strtoul() works.
> - */
> int qemu_strtoul(const char *nptr, const char **endptr, int base,
> unsigned long *result)
> {
> @@ -496,12 +398,6 @@ int qemu_strtoul(const char *nptr, const char **endptr,
> int base,
> return check_strtox_error(nptr, ep, endptr, errno);
> }
>
> -/**
> - * Convert string @nptr to an int64_t.
> - *
> - * Works like qemu_strtol(), except it stores INT64_MAX on overflow,
> - * and INT_MIN on underflow.
> - */
> int qemu_strtoi64(const char *nptr, const char **endptr, int base,
> int64_t *result)
> {
> @@ -521,11 +417,6 @@ int qemu_strtoi64(const char *nptr, const char **endptr,
> int base,
> return check_strtox_error(nptr, ep, endptr, errno);
> }
>
> -/**
> - * Convert string @nptr to an uint64_t.
> - *
> - * Works like qemu_strtoul(), except it stores UINT64_MAX on overflow.
> - */
> int qemu_strtou64(const char *nptr, const char **endptr, int base,
> uint64_t *result)
> {
> @@ -549,30 +440,6 @@ int qemu_strtou64(const char *nptr, const char **endptr,
> int base,
> return check_strtox_error(nptr, ep, endptr, errno);
> }
>
> -/**
> - * Convert string @nptr to a double.
> - *
> - * This is a wrapper around strtod() that is harder to misuse.
> - * Semantics of @nptr and @endptr match strtod() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL. This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows, store +/-HUGE_VAL in @result, depending
> - * on the sign, and return -ERANGE.
> - *
> - * If the conversion underflows, store +/-0.0 in @result, depending on the
> - * sign, and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - */
> int qemu_strtod(const char *nptr, const char **endptr, double *result)
> {
> char *ep;
> @@ -589,12 +456,6 @@ int qemu_strtod(const char *nptr, const char **endptr,
> double *result)
> return check_strtox_error(nptr, ep, endptr, errno);
> }
>
> -/**
> - * Convert string @nptr to a finite double.
> - *
> - * Works like qemu_strtod(), except that "NaN" and "inf" are rejected
> - * with -EINVAL and no conversion is performed.
> - */
> int qemu_strtod_finite(const char *nptr, const char **endptr, double *result)
> {
> double tmp;
> @@ -614,10 +475,6 @@ int qemu_strtod_finite(const char *nptr, const char
> **endptr, double *result)
> return ret;
> }
>
> -/**
> - * Searches for the first occurrence of 'c' in 's', and returns a pointer
> - * to the trailing null byte if none was found.
> - */
> #ifndef HAVE_STRCHRNUL
> const char *qemu_strchrnul(const char *s, int c)
> {
> @@ -629,34 +486,6 @@ const char *qemu_strchrnul(const char *s, int c)
> }
> #endif
>
> -/**
> - * parse_uint:
> - *
> - * @s: String to parse
> - * @value: Destination for parsed integer value
> - * @endptr: Destination for pointer to first character not consumed
> - * @base: integer base, between 2 and 36 inclusive, or 0
> - *
> - * Parse unsigned integer
> - *
> - * 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 address@hidden to 0, address@hidden to
> @s, and
> - * return -EINVAL.
> - *
> - * Set address@hidden to point right beyond the parsed integer (even if the
> integer
> - * overflows or is negative, all digits will be parsed and address@hidden
> will
> - * point right beyond them).
> - *
> - * If the integer is negative, set address@hidden to 0, and return -ERANGE.
> - *
> - * If the integer overflows unsigned long long, set address@hidden to
> - * ULLONG_MAX, and return -ERANGE.
> - *
> - * Else, set address@hidden to the parsed integer, and return 0.
> - */
> int parse_uint(const char *s, unsigned long long *value, char **endptr,
> int base)
> {
> @@ -698,20 +527,6 @@ out:
> return r;
> }
>
> -/**
> - * parse_uint_full:
> - *
> - * @s: String to parse
> - * @value: Destination for parsed integer value
> - * @base: integer base, between 2 and 36 inclusive, or 0
> - *
> - * 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
> address@hidden will
> - * be set to 0.
> - */
> int parse_uint_full(const char *s, unsigned long long *value, int base)
> {
> char *endp;
>
Applied to my trivial-patches branch.
Thanks,
Laurent
- Re: [Qemu-devel] [PATCH v2 2/3] util/cutils: Move ctype macros to "cutils.h", (continued)