[PATCH libmnl] attr: expand mnl_attr_get_uint() documentation

[PATCH libmnl] attr: expand mnl_attr_get_uint() documentation

[Pablo Neira Ayuso]

This function is modelled after rta_getattr_uint() in libnetlink to fetch the
netlink attribute payload of NLA_UINT, although it was extended to make it
universal for 2^3..2^6 byte integers.

Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
---
 src/attr.c | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/attr.c b/src/attr.c
index 399318eebaa8..afabe5fbc8d9 100644
--- a/src/attr.c
+++ b/src/attr.c
@@ -393,7 +393,24 @@ EXPORT_SYMBOL uint64_t mnl_attr_get_u64(const struct nlattr *attr)
  * mnl_attr_get_uint - returns 64-bit unsigned integer attribute.
  * \param attr pointer to netlink attribute
  *
- * This function returns the 64-bit value of the attribute payload.
+ * This helper function reads the variable-length netlink attribute NLA_UINT
+ * that provides a 32-bit or 64-bit integer payload. Its use is recommended only
+ * in these cases.
+ *
+ * Recommended validation for NLA_UINT is:
+ *
+ * \verbatim
+	if (!mnl_attr_validate(attr, NLA_U32) &&
+	    !mnl_attr_validate(attr, NLA_U64)) {
+		perror("mnl_attr_validate");
+		return MNL_CB_ERROR;
+	}
+\endverbatim
+ *
+ * \returns the 64-bit value of the attribute payload. On error, it returns
+ * UINT64_MAX if the length of the netlink attribute is not 2^3..2^6 bytes.
+ * Therefore, there is no way to distinguish between UINT64_MAX and an error.
+ * Also, errno is never set.
  */
 EXPORT_SYMBOL uint64_t mnl_attr_get_uint(const struct nlattr *attr)
 {
-- 
2.30.2

Re: [PATCH libmnl] attr: expand mnl_attr_get_uint() documentation

[Phil Sutter]

On Sun, Oct 13, 2024 at 12:27:25AM +0200, Pablo Neira Ayuso wrote:
> This function is modelled after rta_getattr_uint() in libnetlink to fetch the
> netlink attribute payload of NLA_UINT, although it was extended to make it
> universal for 2^3..2^6 byte integers.
                         ~~~~
This should be bits, not bytes.

> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
> ---
>  src/attr.c | 19 ++++++++++++++++++-
>  1 file changed, 18 insertions(+), 1 deletion(-)
> 
> diff --git a/src/attr.c b/src/attr.c
> index 399318eebaa8..afabe5fbc8d9 100644
> --- a/src/attr.c
> +++ b/src/attr.c
> @@ -393,7 +393,24 @@ EXPORT_SYMBOL uint64_t mnl_attr_get_u64(const struct nlattr *attr)
>   * mnl_attr_get_uint - returns 64-bit unsigned integer attribute.
>   * \param attr pointer to netlink attribute
>   *
> - * This function returns the 64-bit value of the attribute payload.
> + * This helper function reads the variable-length netlink attribute NLA_UINT
> + * that provides a 32-bit or 64-bit integer payload. Its use is recommended only
> + * in these cases.
> + *
> + * Recommended validation for NLA_UINT is:
> + *
> + * \verbatim
> +	if (!mnl_attr_validate(attr, NLA_U32) &&
> +	    !mnl_attr_validate(attr, NLA_U64)) {
> +		perror("mnl_attr_validate");
> +		return MNL_CB_ERROR;
> +	}
> +\endverbatim
> + *
> + * \returns the 64-bit value of the attribute payload. On error, it returns
> + * UINT64_MAX if the length of the netlink attribute is not 2^3..2^6 bytes.
                                                                        ~~~~~
Same here.

Apart from that, LGTM!

Cheers, Phil