From patchwork Mon Aug 8 17:50:19 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacob Keller X-Patchwork-Id: 1664661 X-Patchwork-Delegate: pablo@netfilter.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=intel.com header.i=@intel.com header.a=rsa-sha256 header.s=Intel header.b=IScqwDA4; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=vger.kernel.org (client-ip=2620:137:e000::1:20; helo=out1.vger.email; envelope-from=netfilter-devel-owner@vger.kernel.org; receiver=) Received: from out1.vger.email (out1.vger.email [IPv6:2620:137:e000::1:20]) by bilbo.ozlabs.org (Postfix) with ESMTP id 4M1kJh05smz9sFs for ; Tue, 9 Aug 2022 03:51:00 +1000 (AEST) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S243576AbiHHRuf (ORCPT ); Mon, 8 Aug 2022 13:50:35 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:57036 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S243624AbiHHRud (ORCPT ); Mon, 8 Aug 2022 13:50:33 -0400 Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id DD4681091 for ; Mon, 8 Aug 2022 10:50:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1659981030; x=1691517030; h=from:to:cc:subject:date:message-id:mime-version: content-transfer-encoding; bh=NfM1f1SPHohOzsV1QfTFl75pq2RLCfHgvz9Kw3tJVqo=; b=IScqwDA4GeLLUBNOsjGI0Yk4VT98r+SS1Q75ZMC5CkelTPqi2aqH5lF7 DjhnH2Zoxrlt9YVBZAYzLETgHUw/UW9met5y6C7PQ6P95Q83e1f+asooo YlIIsESB1EwX41db1C3HKu9kOX3ZxFH9sjfWpaVY850VyTlj8RCfVAhkf cW0AENtWakEMRUl3+4Th4ECf86OL4sVKvJohljPhXIcQhFKiXuM8s6bsw 9sWGZIjzYQoFUkpKIlm+JYngBW6EQcl183Fyr28uCu0gz6p94Kg5Nq1ep Cd3nS/KRiO7Qf50cHXGvNSKvxeMm2GYIwv9lANG/5IORWKGTibyLnO+Sv A==; X-IronPort-AV: E=McAfee;i="6400,9594,10433"; a="316574599" X-IronPort-AV: E=Sophos;i="5.93,222,1654585200"; d="scan'208";a="316574599" Received: from orsmga008.jf.intel.com ([10.7.209.65]) by fmsmga101.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 08 Aug 2022 10:50:30 -0700 X-IronPort-AV: E=Sophos;i="5.93,222,1654585200"; d="scan'208";a="632993971" Received: from jekeller-desk.amr.corp.intel.com (HELO jekeller-desk.jekeller.internal) ([10.166.241.7]) by orsmga008-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 08 Aug 2022 10:50:30 -0700 From: Jacob Keller To: Netfilter Devel Cc: Duncan Roe , Pablo Neira Ayuso , Jacob Keller , Duncan Roe Subject: [PATCH libmnl v3 1/2] libmnl: update attribute function comments to use \return Date: Mon, 8 Aug 2022 10:50:19 -0700 Message-Id: <20220808175020.2983706-1-jacob.e.keller@intel.com> X-Mailer: git-send-email 2.37.1.208.ge72d93e88cb2 MIME-Version: 1.0 X-Spam-Status: No, score=-7.7 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_HI, RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,SPF_NONE, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: netfilter-devel@vger.kernel.org Update the function comments in lib/attr.c to use the \return notation, which produces better man page output. Suggested-by: Duncan Roe Signed-off-by: Jacob Keller Acked-by: Duncan Roe --- Changes since v2 * added Duncan's acked-by src/attr.c | 138 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 79 insertions(+), 59 deletions(-) diff --git a/src/attr.c b/src/attr.c index 838eab063981..20d48a370524 100644 --- a/src/attr.c +++ b/src/attr.c @@ -33,7 +33,7 @@ * mnl_attr_get_type - get type of netlink attribute * \param attr pointer to netlink attribute * - * This function returns the attribute type. + * \return the attribute type */ EXPORT_SYMBOL uint16_t mnl_attr_get_type(const struct nlattr *attr) { @@ -44,8 +44,11 @@ EXPORT_SYMBOL uint16_t mnl_attr_get_type(const struct nlattr *attr) * mnl_attr_get_len - get length of netlink attribute * \param attr pointer to netlink attribute * - * This function returns the attribute length that is the attribute header - * plus the attribute payload. + * \return the attribute length + * + * The attribute length is the length of the attribute header plus the + * attribute payload. + * */ EXPORT_SYMBOL uint16_t mnl_attr_get_len(const struct nlattr *attr) { @@ -56,7 +59,7 @@ EXPORT_SYMBOL uint16_t mnl_attr_get_len(const struct nlattr *attr) * mnl_attr_get_payload_len - get the attribute payload-value length * \param attr pointer to netlink attribute * - * This function returns the attribute payload-value length. + * \return the attribute payload-value length */ EXPORT_SYMBOL uint16_t mnl_attr_get_payload_len(const struct nlattr *attr) { @@ -67,7 +70,7 @@ EXPORT_SYMBOL uint16_t mnl_attr_get_payload_len(const struct nlattr *attr) * mnl_attr_get_payload - get pointer to the attribute payload * \param attr pointer to netlink attribute * - * This function return a pointer to the attribute payload. + * \return pointer to the attribute payload */ EXPORT_SYMBOL void *mnl_attr_get_payload(const struct nlattr *attr) { @@ -85,10 +88,12 @@ EXPORT_SYMBOL void *mnl_attr_get_payload(const struct nlattr *attr) * truncated. * * This function does not set errno in case of error since it is intended - * for iterations. Thus, it returns true on success and false on error. + * for iterations. * * The len parameter may be negative in the case of malformed messages during * attribute iteration, that is why we use a signed integer. + * + * \return true if there is room for the attribute, false otherwise */ EXPORT_SYMBOL bool mnl_attr_ok(const struct nlattr *attr, int len) { @@ -101,9 +106,11 @@ EXPORT_SYMBOL bool mnl_attr_ok(const struct nlattr *attr, int len) * mnl_attr_next - get the next attribute in the payload of a netlink message * \param attr pointer to the current attribute * - * This function returns a pointer to the next attribute after the one passed - * as parameter. You have to use mnl_attr_ok() to ensure that the next - * attribute is valid. + * \return a pointer to the next attribute after the one passed in + * + * You have to use mnl_attr_ok() on the returned attribute to ensure that the + * next attribute is valid. + * */ EXPORT_SYMBOL struct nlattr *mnl_attr_next(const struct nlattr *attr) { @@ -116,13 +123,17 @@ EXPORT_SYMBOL struct nlattr *mnl_attr_next(const struct nlattr *attr) * \param max maximum attribute type * * This function allows to check if the attribute type is higher than the - * maximum supported type. If the attribute type is invalid, this function - * returns -1 and errno is explicitly set. On success, this function returns 1. + * maximum supported type. * * Strict attribute checking in user-space is not a good idea since you may * run an old application with a newer kernel that supports new attributes. * This leads to backward compatibility breakages in user-space. Better check * if you support an attribute, if not, skip it. + * + * On an error, errno is explicitly set. + * + * \return 1 if the attribute is valid, -1 otherwise + * */ EXPORT_SYMBOL int mnl_attr_type_valid(const struct nlattr *attr, uint16_t max) { @@ -201,8 +212,11 @@ static const size_t mnl_attr_data_type_len[MNL_TYPE_MAX] = { * \param type data type (see enum mnl_attr_data_type) * * The validation is based on the data type. Specifically, it checks that - * integers (u8, u16, u32 and u64) have enough room for them. This function - * returns -1 in case of error, and errno is explicitly set. + * integers (u8, u16, u32 and u64) have enough room for them. + * + * On an error, errno is explicitly set. + * + * \return 0 on success, -1 on error */ EXPORT_SYMBOL int mnl_attr_validate(const struct nlattr *attr, enum mnl_attr_data_type type) { @@ -223,8 +237,12 @@ EXPORT_SYMBOL int mnl_attr_validate(const struct nlattr *attr, enum mnl_attr_dat * \param exp_len expected attribute data size * * This function allows to perform a more accurate validation for attributes - * whose size is variable. If the size of the attribute is not what we expect, - * this functions returns -1 and errno is explicitly set. + * whose size is variable. + * + * On an error, errno is explicitly set. + * + * \return 0 if the attribute is valid and fits within the expected length, -1 + * otherwise */ EXPORT_SYMBOL int mnl_attr_validate2(const struct nlattr *attr, enum mnl_attr_data_type type, @@ -249,8 +267,8 @@ EXPORT_SYMBOL int mnl_attr_validate2(const struct nlattr *attr, * usually happens at this stage or you can use any other data structure (such * as lists or trees). * - * This function propagates the return value of the callback, which can be - * MNL_CB_ERROR, MNL_CB_OK or MNL_CB_STOP. + * \return propagated value from callback, one of MNL_CB_ERROR, MNL_CB_STOP + * or MNL_CB_OK */ EXPORT_SYMBOL int mnl_attr_parse(const struct nlmsghdr *nlh, unsigned int offset, mnl_attr_cb_t cb, @@ -276,8 +294,8 @@ EXPORT_SYMBOL int mnl_attr_parse(const struct nlmsghdr *nlh, * usually happens at this stage or you can use any other data structure (such * as lists or trees). * - * This function propagates the return value of the callback, which can be - * MNL_CB_ERROR, MNL_CB_OK or MNL_CB_STOP. +* \return propagated value from callback, one of MNL_CB_ERROR, MNL_CB_STOP +* or MNL_CB_OK */ EXPORT_SYMBOL int mnl_attr_parse_nested(const struct nlattr *nested, mnl_attr_cb_t cb, void *data) @@ -307,8 +325,8 @@ EXPORT_SYMBOL int mnl_attr_parse_nested(const struct nlattr *nested, * located at some payload offset. You can then put the attributes in one array * as usual, or you can use any other data structure (such as lists or trees). * - * This function propagates the return value of the callback, which can be - * MNL_CB_ERROR, MNL_CB_OK or MNL_CB_STOP. + * \return propagated value from callback, one of MNL_CB_ERROR, MNL_CB_STOP + * or MNL_CB_OK */ EXPORT_SYMBOL int mnl_attr_parse_payload(const void *payload, size_t payload_len, @@ -324,10 +342,10 @@ EXPORT_SYMBOL int mnl_attr_parse_payload(const void *payload, } /** - * mnl_attr_get_u8 - returns 8-bit unsigned integer attribute payload + * mnl_attr_get_u8 - get 8-bit unsigned integer attribute payload * \param attr pointer to netlink attribute * - * This function returns the 8-bit value of the attribute payload. + * \return 8-bit value of the attribute payload */ EXPORT_SYMBOL uint8_t mnl_attr_get_u8(const struct nlattr *attr) { @@ -335,10 +353,10 @@ EXPORT_SYMBOL uint8_t mnl_attr_get_u8(const struct nlattr *attr) } /** - * mnl_attr_get_u16 - returns 16-bit unsigned integer attribute payload + * mnl_attr_get_u16 - get 16-bit unsigned integer attribute payload * \param attr pointer to netlink attribute * - * This function returns the 16-bit value of the attribute payload. + * \return 16-bit value of the attribute payload */ EXPORT_SYMBOL uint16_t mnl_attr_get_u16(const struct nlattr *attr) { @@ -346,10 +364,10 @@ EXPORT_SYMBOL uint16_t mnl_attr_get_u16(const struct nlattr *attr) } /** - * mnl_attr_get_u32 - returns 32-bit unsigned integer attribute payload + * mnl_attr_get_u32 - get 32-bit unsigned integer attribute payload * \param attr pointer to netlink attribute * - * This function returns the 32-bit value of the attribute payload. + * \return 32-bit value of the attribute payload */ EXPORT_SYMBOL uint32_t mnl_attr_get_u32(const struct nlattr *attr) { @@ -357,12 +375,12 @@ EXPORT_SYMBOL uint32_t mnl_attr_get_u32(const struct nlattr *attr) } /** - * mnl_attr_get_u64 - returns 64-bit unsigned integer attribute. + * mnl_attr_get_u64 - get 64-bit unsigned integer attribute * \param attr pointer to netlink attribute * - * This function returns the 64-bit value of the attribute payload. This - * function is align-safe, since accessing 64-bit Netlink attributes is a - * common source of alignment issues. + * This function reads the 64-bit nlattr payload in an alignment safe manner. + * + * \return 64-bit value of the attribute payload */ EXPORT_SYMBOL uint64_t mnl_attr_get_u64(const struct nlattr *attr) { @@ -372,10 +390,10 @@ EXPORT_SYMBOL uint64_t mnl_attr_get_u64(const struct nlattr *attr) } /** - * mnl_attr_get_str - returns pointer to string attribute. + * mnl_attr_get_str - get pointer to string attribute * \param attr pointer to netlink attribute * - * This function returns the payload of string attribute value. + * \return string pointer of the attribute payload */ EXPORT_SYMBOL const char *mnl_attr_get_str(const struct nlattr *attr) { @@ -508,8 +526,9 @@ EXPORT_SYMBOL void mnl_attr_put_strz(struct nlmsghdr *nlh, uint16_t type, * \param type netlink attribute type * * This function adds the attribute header that identifies the beginning of - * an attribute nest. This function always returns a valid pointer to the - * beginning of the nest. + * an attribute nest. + * + * \return valid pointer to the beginning of the nest */ EXPORT_SYMBOL struct nlattr *mnl_attr_nest_start(struct nlmsghdr *nlh, uint16_t type) @@ -534,8 +553,9 @@ EXPORT_SYMBOL struct nlattr *mnl_attr_nest_start(struct nlmsghdr *nlh, * This function first checks that the data can be added to the message * (fits into the buffer) and then updates the length field of the Netlink * message (nlmsg_len) by adding the size (header + payload) of the new - * attribute. The function returns true if the attribute could be added - * to the message, otherwise false is returned. + * attribute. + * + * \return true if the attribute could be added, false otherwise */ EXPORT_SYMBOL bool mnl_attr_put_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, size_t len, @@ -557,8 +577,9 @@ EXPORT_SYMBOL bool mnl_attr_put_check(struct nlmsghdr *nlh, size_t buflen, * This function first checks that the data can be added to the message * (fits into the buffer) and then updates the length field of the Netlink * message (nlmsg_len) by adding the size (header + payload) of the new - * attribute. The function returns true if the attribute could be added - * to the message, otherwise false is returned. + * attribute. + * + * \return true if the attribute could be added, false otherwise */ EXPORT_SYMBOL bool mnl_attr_put_u8_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, uint8_t data) @@ -576,10 +597,9 @@ EXPORT_SYMBOL bool mnl_attr_put_u8_check(struct nlmsghdr *nlh, size_t buflen, * This function first checks that the data can be added to the message * (fits into the buffer) and then updates the length field of the Netlink * message (nlmsg_len) by adding the size (header + payload) of the new - * attribute. The function returns true if the attribute could be added - * to the message, otherwise false is returned. - * This function updates the length field of the Netlink message (nlmsg_len) - * by adding the size (header + payload) of the new attribute. + * attribute. + * + * \return true if the attribute could be added, false otherwise */ EXPORT_SYMBOL bool mnl_attr_put_u16_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, uint16_t data) @@ -597,10 +617,9 @@ EXPORT_SYMBOL bool mnl_attr_put_u16_check(struct nlmsghdr *nlh, size_t buflen, * This function first checks that the data can be added to the message * (fits into the buffer) and then updates the length field of the Netlink * message (nlmsg_len) by adding the size (header + payload) of the new - * attribute. The function returns true if the attribute could be added - * to the message, otherwise false is returned. - * This function updates the length field of the Netlink message (nlmsg_len) - * by adding the size (header + payload) of the new attribute. + * attribute. + * + * \return true if the attribute could be added, false otherwise */ EXPORT_SYMBOL bool mnl_attr_put_u32_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, uint32_t data) @@ -618,10 +637,9 @@ EXPORT_SYMBOL bool mnl_attr_put_u32_check(struct nlmsghdr *nlh, size_t buflen, * This function first checks that the data can be added to the message * (fits into the buffer) and then updates the length field of the Netlink * message (nlmsg_len) by adding the size (header + payload) of the new - * attribute. The function returns true if the attribute could be added - * to the message, otherwise false is returned. - * This function updates the length field of the Netlink message (nlmsg_len) - * by adding the size (header + payload) of the new attribute. + * attribute. + * + * \return true if the attribute could be added, false otherwise */ EXPORT_SYMBOL bool mnl_attr_put_u64_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, uint64_t data) @@ -639,10 +657,9 @@ EXPORT_SYMBOL bool mnl_attr_put_u64_check(struct nlmsghdr *nlh, size_t buflen, * This function first checks that the data can be added to the message * (fits into the buffer) and then updates the length field of the Netlink * message (nlmsg_len) by adding the size (header + payload) of the new - * attribute. The function returns true if the attribute could be added - * to the message, otherwise false is returned. - * This function updates the length field of the Netlink message (nlmsg_len) - * by adding the size (header + payload) of the new attribute. + * attribute. + * + * \return true if the attribute could be added, false otherwise */ EXPORT_SYMBOL bool mnl_attr_put_str_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, const char *data) @@ -663,8 +680,9 @@ EXPORT_SYMBOL bool mnl_attr_put_str_check(struct nlmsghdr *nlh, size_t buflen, * This function first checks that the data can be added to the message * (fits into the buffer) and then updates the length field of the Netlink * message (nlmsg_len) by adding the size (header + payload) of the new - * attribute. The function returns true if the attribute could be added - * to the message, otherwise false is returned. + * attribute. + * + * \return true if the attribute could be added, false otherwise */ EXPORT_SYMBOL bool mnl_attr_put_strz_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, const char *data) @@ -679,8 +697,10 @@ EXPORT_SYMBOL bool mnl_attr_put_strz_check(struct nlmsghdr *nlh, size_t buflen, * \param type netlink attribute type * * This function adds the attribute header that identifies the beginning of - * an attribute nest. If the nested attribute cannot be added then NULL, - * otherwise valid pointer to the beginning of the nest is returned. + * an attribute nest. + * + * \return NULL if the attribute cannot be added, otherwise a pointer to the + * beginning of the nest */ EXPORT_SYMBOL struct nlattr *mnl_attr_nest_start_check(struct nlmsghdr *nlh, size_t buflen, From patchwork Mon Aug 8 17:50:20 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacob Keller X-Patchwork-Id: 1664662 X-Patchwork-Delegate: pablo@netfilter.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=intel.com header.i=@intel.com header.a=rsa-sha256 header.s=Intel header.b=BBo4+n24; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=vger.kernel.org (client-ip=2620:137:e000::1:20; helo=out1.vger.email; envelope-from=netfilter-devel-owner@vger.kernel.org; receiver=) Received: from out1.vger.email (out1.vger.email [IPv6:2620:137:e000::1:20]) by bilbo.ozlabs.org (Postfix) with ESMTP id 4M1kJh31mfz9sGR for ; Tue, 9 Aug 2022 03:51:00 +1000 (AEST) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S243624AbiHHRuf (ORCPT ); Mon, 8 Aug 2022 13:50:35 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:57046 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S243659AbiHHRue (ORCPT ); Mon, 8 Aug 2022 13:50:34 -0400 Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 39614E10 for ; Mon, 8 Aug 2022 10:50:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1659981033; x=1691517033; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=fiHmKJYXSjL2yyY0O5s6hyYvpUr+4UEGwAxKOYJViHs=; b=BBo4+n24PtFbEQz+knyvBg8AR8/zw3cQGA/3/CEQ+MmLeB7ZcrO9Fnol l8BS9iEQ51MDr2gBxhp7dIn8j9NXXk33uW1fh5kL3qgjKIX/dhyZPuA8b BAalaA7UhbJK77e5p3oD50NmoeYgdbal+Fj1qaqg3pqZiFim3FIOjax01 lCXapKEVUKyAKVCVdvUt3Z/3PS1+fBvWzkr0/xPX5nM3xg3PVR8hmpr0y eNSt+fd/OOl/n5gMoaqND+q0Q3dOP+7lSrk0uw1dfwZH+tMgQnN9uHuFr 07WjKf7+0MmBHn/biN/QDABE6LrVv3mtX05mw0cbz4qmjjA4xOE/sDYLk w==; X-IronPort-AV: E=McAfee;i="6400,9594,10433"; a="316574602" X-IronPort-AV: E=Sophos;i="5.93,222,1654585200"; d="scan'208";a="316574602" Received: from orsmga008.jf.intel.com ([10.7.209.65]) by fmsmga101.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 08 Aug 2022 10:50:30 -0700 X-IronPort-AV: E=Sophos;i="5.93,222,1654585200"; d="scan'208";a="632993975" Received: from jekeller-desk.amr.corp.intel.com (HELO jekeller-desk.jekeller.internal) ([10.166.241.7]) by orsmga008-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 08 Aug 2022 10:50:30 -0700 From: Jacob Keller To: Netfilter Devel Cc: Duncan Roe , Pablo Neira Ayuso , Jacob Keller Subject: [PATCH libmnl v3 2/2] libmnl: add support for signed types Date: Mon, 8 Aug 2022 10:50:20 -0700 Message-Id: <20220808175020.2983706-2-jacob.e.keller@intel.com> X-Mailer: git-send-email 2.37.1.208.ge72d93e88cb2 In-Reply-To: <20220808175020.2983706-1-jacob.e.keller@intel.com> References: <20220808175020.2983706-1-jacob.e.keller@intel.com> MIME-Version: 1.0 X-Spam-Status: No, score=-7.7 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_HI, RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,SPF_NONE, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: netfilter-devel@vger.kernel.org libmnl has get and put functions for unsigned integer types. It lacks support for the signed variations. On some level this is technically sufficient. A user could use the unsigned variations and then cast to a signed value at use. However, this makes resulting code in the application more difficult to follow. Introduce signed variations of the integer get and put functions. Signed-off-by: Jacob Keller --- Changes since v2 * Fixed the ABI breakage (oops!) include/libmnl/libmnl.h | 16 ++++ src/attr.c | 194 +++++++++++++++++++++++++++++++++++++++- 2 files changed, 209 insertions(+), 1 deletion(-) diff --git a/include/libmnl/libmnl.h b/include/libmnl/libmnl.h index 4bd0b92e8742..ccee4948ff2f 100644 --- a/include/libmnl/libmnl.h +++ b/include/libmnl/libmnl.h @@ -92,6 +92,10 @@ extern uint8_t mnl_attr_get_u8(const struct nlattr *attr); extern uint16_t mnl_attr_get_u16(const struct nlattr *attr); extern uint32_t mnl_attr_get_u32(const struct nlattr *attr); extern uint64_t mnl_attr_get_u64(const struct nlattr *attr); +extern int8_t mnl_attr_get_s8(const struct nlattr *attr); +extern int16_t mnl_attr_get_s16(const struct nlattr *attr); +extern int32_t mnl_attr_get_s32(const struct nlattr *attr); +extern int64_t mnl_attr_get_s64(const struct nlattr *attr); extern const char *mnl_attr_get_str(const struct nlattr *attr); /* TLV attribute putters */ @@ -100,6 +104,10 @@ extern void mnl_attr_put_u8(struct nlmsghdr *nlh, uint16_t type, uint8_t data); extern void mnl_attr_put_u16(struct nlmsghdr *nlh, uint16_t type, uint16_t data); extern void mnl_attr_put_u32(struct nlmsghdr *nlh, uint16_t type, uint32_t data); extern void mnl_attr_put_u64(struct nlmsghdr *nlh, uint16_t type, uint64_t data); +extern void mnl_attr_put_s8(struct nlmsghdr *nlh, uint16_t type, int8_t data); +extern void mnl_attr_put_s16(struct nlmsghdr *nlh, uint16_t type, int16_t data); +extern void mnl_attr_put_s32(struct nlmsghdr *nlh, uint16_t type, int32_t data); +extern void mnl_attr_put_s64(struct nlmsghdr *nlh, uint16_t type, int64_t data); extern void mnl_attr_put_str(struct nlmsghdr *nlh, uint16_t type, const char *data); extern void mnl_attr_put_strz(struct nlmsghdr *nlh, uint16_t type, const char *data); @@ -109,6 +117,10 @@ extern bool mnl_attr_put_u8_check(struct nlmsghdr *nlh, size_t buflen, uint16_t extern bool mnl_attr_put_u16_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, uint16_t data); extern bool mnl_attr_put_u32_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, uint32_t data); extern bool mnl_attr_put_u64_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, uint64_t data); +extern bool mnl_attr_put_s8_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, int8_t data); +extern bool mnl_attr_put_s16_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, int16_t data); +extern bool mnl_attr_put_s32_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, int32_t data); +extern bool mnl_attr_put_s64_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, int64_t data); extern bool mnl_attr_put_str_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, const char *data); extern bool mnl_attr_put_strz_check(struct nlmsghdr *nlh, size_t buflen, uint16_t type, const char *data); @@ -134,6 +146,10 @@ enum mnl_attr_data_type { MNL_TYPE_NESTED_COMPAT, MNL_TYPE_NUL_STRING, MNL_TYPE_BINARY, + MNL_TYPE_S8, + MNL_TYPE_S16, + MNL_TYPE_S32, + MNL_TYPE_S64, MNL_TYPE_MAX, }; diff --git a/src/attr.c b/src/attr.c index 20d48a370524..2f31ecbe8f7a 100644 --- a/src/attr.c +++ b/src/attr.c @@ -203,6 +203,10 @@ static const size_t mnl_attr_data_type_len[MNL_TYPE_MAX] = { [MNL_TYPE_U16] = sizeof(uint16_t), [MNL_TYPE_U32] = sizeof(uint32_t), [MNL_TYPE_U64] = sizeof(uint64_t), + [MNL_TYPE_S8] = sizeof(int8_t), + [MNL_TYPE_S16] = sizeof(int16_t), + [MNL_TYPE_S32] = sizeof(int32_t), + [MNL_TYPE_S64] = sizeof(int64_t), [MNL_TYPE_MSECS] = sizeof(uint64_t), }; @@ -390,7 +394,55 @@ EXPORT_SYMBOL uint64_t mnl_attr_get_u64(const struct nlattr *attr) } /** - * mnl_attr_get_str - get pointer to string attribute + * mnl_attr_get_s8 - get 8-bit signed integer attribute payload + * \param attr pointer to netlink attribute + * + * \return 8-bit value of the attribute payload + */ +EXPORT_SYMBOL int8_t mnl_attr_get_s8(const struct nlattr *attr) +{ + return *((int8_t *)mnl_attr_get_payload(attr)); +} + +/** + * mnl_attr_get_s16 - get 16-bit signed integer attribute payload + * \param attr pointer to netlink attribute + * + * \return 16-bit value of the attribute payload + */ +EXPORT_SYMBOL int16_t mnl_attr_get_s16(const struct nlattr *attr) +{ + return *((int16_t *)mnl_attr_get_payload(attr)); +} + +/** + * mnl_attr_get_s32 - get 32-bit signed integer attribute payload + * \param attr pointer to netlink attribute + * + * \return 32-bit value of the attribute payload + */ +EXPORT_SYMBOL int32_t mnl_attr_get_s32(const struct nlattr *attr) +{ + return *((int32_t *)mnl_attr_get_payload(attr)); +} + +/** + * mnl_attr_get_s64 - get 64-bit signed integer attribute payload + * \param attr pointer to netlink attribute + * + * This function reads the 64-bit nlattr payload in an alignment safe manner. + * + * \return 64-bit value of the attribute payload + */ +EXPORT_SYMBOL int64_t mnl_attr_get_s64(const struct nlattr *attr) +{ + int64_t tmp; + memcpy(&tmp, mnl_attr_get_payload(attr), sizeof(tmp)); + return tmp; +} + +/** + * mnl_attr_get_str - get pointer to string attribute * \param attr pointer to netlink attribute * * \return string pointer of the attribute payload @@ -487,6 +539,66 @@ EXPORT_SYMBOL void mnl_attr_put_u64(struct nlmsghdr *nlh, uint16_t type, mnl_attr_put(nlh, type, sizeof(uint64_t), &data); } +/** + * mnl_attr_put_s8 - add 8-bit signed integer attribute to netlink message + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param data 8-bit signed integer data that is stored by the new attribute + * + * This function updates the length field of the Netlink message (nlmsg_len) + * by adding the size (header + payload) of the new attribute. + */ +EXPORT_SYMBOL void mnl_attr_put_s8(struct nlmsghdr *nlh, uint16_t type, + int8_t data) +{ + mnl_attr_put(nlh, type, sizeof(int8_t), &data); +} + +/** + * mnl_attr_put_s16 - add 16-bit signed integer attribute to netlink message + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param data 16-bit signed integer data that is stored by the new attribute + * + * This function updates the length field of the Netlink message (nlmsg_len) + * by adding the size (header + payload) of the new attribute. + */ +EXPORT_SYMBOL void mnl_attr_put_s16(struct nlmsghdr *nlh, uint16_t type, + int16_t data) +{ + mnl_attr_put(nlh, type, sizeof(int16_t), &data); +} + +/** + * mnl_attr_put_s32 - add 32-bit signed integer attribute to netlink message + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param data 32-bit signed integer data that is stored by the new attribute + * + * This function updates the length field of the Netlink message (nlmsg_len) + * by adding the size (header + payload) of the new attribute. + */ +EXPORT_SYMBOL void mnl_attr_put_s32(struct nlmsghdr *nlh, uint16_t type, + int32_t data) +{ + mnl_attr_put(nlh, type, sizeof(int32_t), &data); +} + +/** + * mnl_attr_put_s64 - add 64-bit signed integer attribute to netlink message + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param data 64-bit signed integer data that is stored by the new attribute + * + * This function updates the length field of the Netlink message (nlmsg_len) + * by adding the size (header + payload) of the new attribute. + */ +EXPORT_SYMBOL void mnl_attr_put_s64(struct nlmsghdr *nlh, uint16_t type, + int64_t data) +{ + mnl_attr_put(nlh, type, sizeof(int64_t), &data); +} + /** * mnl_attr_put_str - add string attribute to netlink message * \param nlh pointer to the netlink message @@ -647,6 +759,86 @@ EXPORT_SYMBOL bool mnl_attr_put_u64_check(struct nlmsghdr *nlh, size_t buflen, return mnl_attr_put_check(nlh, buflen, type, sizeof(uint64_t), &data); } +/** + * mnl_attr_put_s8_check - add 8-bit signed int attribute to netlink message + * \param nlh pointer to the netlink message + * \param buflen size of buffer which stores the message + * \param type netlink attribute type + * \param data 8-bit signed integer data that is stored by the new attribute + * + * This function first checks that the data can be added to the message + * (fits into the buffer) and then updates the length field of the Netlink + * message (nlmsg_len) by adding the size (header + payload) of the new + * attribute. + * + * \return true if the attribute could be added, false otherwise + */ +EXPORT_SYMBOL bool mnl_attr_put_s8_check(struct nlmsghdr *nlh, size_t buflen, + uint16_t type, int8_t data) +{ + return mnl_attr_put_check(nlh, buflen, type, sizeof(data), &data); +} + +/** + * mnl_attr_put_s16_check - add 16-bit signed int attribute to netlink message + * \param nlh pointer to the netlink message + * \param buflen size of buffer which stores the message + * \param type netlink attribute type + * \param data 16-bit signed integer data that is stored by the new attribute + * + * This function first checks that the data can be added to the message + * (fits into the buffer) and then updates the length field of the Netlink + * message (nlmsg_len) by adding the size (header + payload) of the new + * attribute. + * + * \return true if the attribute could be added, false otherwise + */ +EXPORT_SYMBOL bool mnl_attr_put_s16_check(struct nlmsghdr *nlh, size_t buflen, + uint16_t type, int16_t data) +{ + return mnl_attr_put_check(nlh, buflen, type, sizeof(data), &data); +} + +/** + * mnl_attr_put_s32_check - add 32-bit signed int attribute to netlink message + * \param nlh pointer to the netlink message + * \param buflen size of buffer which stores the message + * \param type netlink attribute type + * \param data 32-bit signed integer data that is stored by the new attribute + * + * This function first checks that the data can be added to the message + * (fits into the buffer) and then updates the length field of the Netlink + * message (nlmsg_len) by adding the size (header + payload) of the new + * attribute. + * + * \return true if the attribute could be added, false otherwise + */ +EXPORT_SYMBOL bool mnl_attr_put_s32_check(struct nlmsghdr *nlh, size_t buflen, + uint16_t type, int32_t data) +{ + return mnl_attr_put_check(nlh, buflen, type, sizeof(data), &data); +} + +/** + * mnl_attr_put_s64_check - add 64-bit signed int attribute to netlink message + * \param nlh pointer to the netlink message + * \param buflen size of buffer which stores the message + * \param type netlink attribute type + * \param data 64-bit signed integer data that is stored by the new attribute + * + * This function first checks that the data can be added to the message + * (fits into the buffer) and then updates the length field of the Netlink + * message (nlmsg_len) by adding the size (header + payload) of the new + * attribute. + * + * \return true if the attribute could be added, false otherwise + */ +EXPORT_SYMBOL bool mnl_attr_put_s64_check(struct nlmsghdr *nlh, size_t buflen, + uint16_t type, int64_t data) +{ + return mnl_attr_put_check(nlh, buflen, type, sizeof(data), &data); +} + /** * mnl_attr_put_str_check - add string attribute to netlink message * \param nlh pointer to the netlink message