summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPablo Neira Ayuso <pablo@netfilter.org>2010-03-22 12:18:23 +0100
committerPablo Neira Ayuso <pablo@netfilter.org>2010-03-22 12:18:23 +0100
commitc5a4f3d7738f8172de40112cf4a02fbd4b0a9902 (patch)
tree59eaf378e4ec4762c921d5d869fd601b74c71629
parent3cc6ba530042288363a048299f2d6a38517db308 (diff)
finish API documentation
This patch may contain errors but we can review them and fix them later, better to have it in the tree (to allow others to contribute) to keep it in my local tree.
-rw-r--r--src/attr.c140
-rw-r--r--src/callback.c1
-rw-r--r--src/msg.c7
3 files changed, 129 insertions, 19 deletions
diff --git a/src/attr.c b/src/attr.c
index a724be0..c1f0abf 100644
--- a/src/attr.c
+++ b/src/attr.c
@@ -8,17 +8,19 @@
#include <libmnl/libmnl.h>
#include <string.h>
-/**
- * Netlink attribute:
+/*
+ * Netlink Type-Length-Value (TLV) attribute:
*
* |<-- 2 bytes -->|<-- 2 bytes -->|<-- variable -->|
* -------------------------------------------------
* | length | type | value |
* -------------------------------------------------
+ * |<--------- header ------------>|<-- payload --->|
*/
/**
* mnl_attr_get_type - get the attribute type of a netlink message
+ * @attr: pointer to netlink attribute
*
* This function returns the attribute type.
*/
@@ -29,8 +31,9 @@ u_int16_t mnl_attr_get_type(const struct nlattr *attr)
/**
* mnl_attr_get_len - get the attribute length
+ * @attr: pointer to netlink attribute
*
- * This function returns the attribute length.
+ * This function returns the attribute length, including the attribute header.
*/
u_int16_t mnl_attr_get_len(const struct nlattr *attr)
{
@@ -38,9 +41,10 @@ u_int16_t mnl_attr_get_len(const struct nlattr *attr)
}
/**
- * mnl_attr_get_payload_len - get the attribute payload length
+ * mnl_attr_get_payload_len - get the attribute payload-value length
+ * @attr: pointer to netlink attribute
*
- * This function returns the attribute payload length.
+ * This function returns the attribute payload-value length.
*/
u_int16_t mnl_attr_get_payload_len(const struct nlattr *attr)
{
@@ -58,13 +62,13 @@ void *mnl_attr_get_data(const struct nlattr *attr)
}
/**
- * mnl_attr_ok - check a there is room for an attribute
+ * mnl_attr_ok - check a there is room for an attribute in a buffer
* @nlh: attribute that we want to check
* @len: remaining bytes in a buffer that contains the attribute
*
* This function is used to check that a buffer that contains an attribute
* has enough room for the attribute that it stores, ie. this function can
- * be used to verify that an attribute is not malformed nor truncated.
+ * be used to verify that an attribute is neither malformed nor truncated.
*/
int mnl_attr_ok(const struct nlattr *attr, int len)
{
@@ -88,18 +92,21 @@ struct nlattr *mnl_attr_next(const struct nlattr *attr, int *len)
}
/**
- * mnl_attr_parse - returns an array with the attributes in a message
+ * mnl_attr_parse_at_offset - returns an array of attributes from offset
+ * @nlh: pointer to netlink message
+ * @offset: offset to start parse from
* @tb: array of pointers to the attribute found
- * @tb_size: size of the attribute array
- * @attr: first attribute in the stream
- * @len: remaining bytes in the buffer that contain attributes
+ * @max: size of the attribute array
+ *
+ * This functions zeroes the array of pointers. Thus, you don't need to
+ * initialize this array.
*
- * This function returns a table of pointers to the attributes that has been
+ * This function returns an array of pointers to the attributes that has been
* found in a netlink payload. This function return 0 on sucess, and >0 to
* indicate the number of bytes the remaining bytes.
*/
int mnl_attr_parse_at_offset(const struct nlmsghdr *nlh, int offset,
- struct nlattr *tb[], int max)
+ struct nlattr *tb[], int max)
{
struct nlattr *attr = mnl_nlmsg_get_data_offset(nlh, offset);
int len = mnl_nlmsg_get_len(nlh);
@@ -114,13 +121,39 @@ int mnl_attr_parse_at_offset(const struct nlmsghdr *nlh, int offset,
return len;
}
+/**
+ * mnl_attr_parse - returns an array with the attributes in the netlink message
+ * @nlh: pointer to netlink message header
+ * @tb: array of pointers to the attribute found
+ * @max: size of the attribute array
+ *
+ * This functions zeroes the array of pointers. Thus, you don't need to
+ * initialize this array.
+ *
+ * This function returns an array of pointers to the attributes that has been
+ * found in a netlink payload. This function return 0 on sucess, and >0 to
+ * indicate the number of bytes the remaining bytes.
+ */
int mnl_attr_parse(const struct nlmsghdr *nlh, struct nlattr *tb[], int max)
{
return mnl_attr_parse_at_offset(nlh, 0, tb, max);
}
+/**
+ * mnl_attr_parse_nested - returns an array with the attributes from nested
+ * @nested: pointer to netlink attribute that contains a nest
+ * @tb: array of pointers to the attribute found
+ * @max: size of the attribute array
+ *
+ * This functions zeroes the array of pointers. Thus, you don't need to
+ * initialize this array.
+ *
+ * This function returns an array of pointers to the attributes that has been
+ * found in a netlink payload. This function return 0 on sucess, and >0 to
+ * indicate the number of bytes the remaining bytes.
+ */
int mnl_attr_parse_nested(const struct nlattr *nested,
- struct nlattr *tb[], int max)
+ struct nlattr *tb[], int max)
{
struct nlattr *attr = mnl_attr_get_data(nested);
int len = mnl_attr_get_payload_len(nested);
@@ -135,27 +168,45 @@ int mnl_attr_parse_nested(const struct nlattr *nested,
return len;
}
+/**
+ * mnl_attr_get_u8 - returns 8-bit unsigned integer attribute.
+ * @attr: pointer to netlink attribute
+ *
+ * This function returns the 8-bit value of a netlink attribute.
+ */
u_int8_t mnl_attr_get_u8(const struct nlattr *attr)
{
return *((u_int8_t *)mnl_attr_get_data(attr));
}
+/**
+ * mnl_attr_get_u16 - returns 16-bit unsigned integer attribute.
+ * @attr: pointer to netlink attribute
+ *
+ * This function returns the 16-bit value of a netlink attribute.
+ */
u_int16_t mnl_attr_get_u16(const struct nlattr *attr)
{
return *((u_int16_t *)mnl_attr_get_data(attr));
}
+/**
+ * mnl_attr_get_u32 - returns 32-bit unsigned integer attribute.
+ * @attr: pointer to netlink attribute
+ *
+ * This function returns the 32-bit value of a netlink attribute.
+ */
u_int32_t mnl_attr_get_u32(const struct nlattr *attr)
{
return *((u_int32_t *)mnl_attr_get_data(attr));
}
/**
- * mnl_attr_get_u64 - returns an arra
- * @attr: netlink attribute
+ * mnl_attr_get_u64 - returns 64-bit unsigned integer attribute.
+ * @attr: pointer to netlink attribute
*
- * This function returns the payload of a 64-bits attribute. This function
- * is align-safe since accessing 64-bits Netlink attributes is a common
+ * This function returns the payload of a 64-bit attribute. This function
+ * is align-safe since accessing 64-bit Netlink attributes is a common
* source of alignment issues.
*/
u_int64_t mnl_attr_get_u64(const struct nlattr *attr)
@@ -165,11 +216,24 @@ u_int64_t mnl_attr_get_u64(const struct nlattr *attr)
return tmp;
}
+/**
+ * mnl_attr_get_str - returns pointer to string attribute.
+ * @attr: pointer to netlink attribute
+ *
+ * This function returns the payload of string attribute value.
+ */
const char *mnl_attr_get_str(const struct nlattr *attr)
{
return (const char *)mnl_attr_get_data(attr);
}
+/**
+ * mnl_attr_put - add an attribute to netlink message
+ * @nlh: pointer to the netlink message
+ * @type: netlink attribute type
+ * @len: netlink attribute payload size
+ * @data: pointer to the data that is stored by the new attribute
+ */
void mnl_attr_put(struct nlmsghdr *nlh, int type, size_t len, const void *data)
{
struct nlattr *attr = mnl_nlmsg_get_tail(nlh);
@@ -181,31 +245,71 @@ void mnl_attr_put(struct nlmsghdr *nlh, int type, size_t len, const void *data)
nlh->nlmsg_len += mnl_align(payload_len);
}
+/**
+ * mnl_attr_put_u8 - add 8-bit unsigned integer attribute to netlink message
+ * @nlh: pointer to the netlink message
+ * @type: netlink attribute type
+ * @len: netlink attribute payload size
+ * @data: 8-bit unsigned integer data that is stored by the new attribute
+ */
void mnl_attr_put_u8(struct nlmsghdr *nlh, int type, u_int8_t data)
{
mnl_attr_put(nlh, type, sizeof(u_int8_t), &data);
}
+/**
+ * mnl_attr_put_u16 - add 16-bit unsigned integer attribute to netlink message
+ * @nlh: pointer to the netlink message
+ * @type: netlink attribute type
+ * @data: 16-bit unsigned integer data that is stored by the new attribute
+ */
void mnl_attr_put_u16(struct nlmsghdr *nlh, int type, u_int16_t data)
{
mnl_attr_put(nlh, type, sizeof(u_int16_t), &data);
}
+/**
+ * mnl_attr_put_u32 - add 32-bit unsigned integer attribute to netlink message
+ * @nlh: pointer to the netlink message
+ * @type: netlink attribute type
+ * @data: 32-bit unsigned integer data that is stored by the new attribute
+ */
void mnl_attr_put_u32(struct nlmsghdr *nlh, int type, u_int32_t data)
{
mnl_attr_put(nlh, type, sizeof(u_int32_t), &data);
}
+/**
+ * mnl_attr_put_u64 - add 64-bit unsigned integer attribute to netlink message
+ * @nlh: pointer to the netlink message
+ * @type: netlink attribute type
+ * @data: 64-bit unsigned integer data that is stored by the new attribute
+ */
void mnl_attr_put_u64(struct nlmsghdr *nlh, int type, u_int64_t data)
{
mnl_attr_put(nlh, type, sizeof(u_int64_t), &data);
}
+/**
+ * mnl_attr_put_str - add string attribute to netlink message
+ * @nlh: pointer to the netlink message
+ * @type: netlink attribute type
+ * @data: pointer to string data that is stored by the new attribute
+ */
void mnl_attr_put_str(struct nlmsghdr *nlh, int type, const void *data)
{
mnl_attr_put(nlh, type, strlen(data), data);
}
+/**
+ * mnl_attr_put_str_null - add string attribute to netlink message
+ * @nlh: pointer to the netlink message
+ * @type: netlink attribute type
+ * @data: pointer to string data that is stored by the new attribute
+ *
+ * This function is similar to mnl_attr_put_str but it includes the NULL
+ * terminator at the end of the string.
+ */
void mnl_attr_put_str_null(struct nlmsghdr *nlh, int type, const void *data)
{
mnl_attr_put(nlh, type, strlen(data)+1, data);
diff --git a/src/callback.c b/src/callback.c
index 3fc883e..2f2da50 100644
--- a/src/callback.c
+++ b/src/callback.c
@@ -111,7 +111,6 @@ out:
* This function returns -1 in case of error, 0 if we have received a
* NLMSG_DONE message or the callback has explicitly returned MNL_CB_STOP.
*/
-
int mnl_cb_run(const char *buf, int numbytes, unsigned int seq,
mnl_cb_t cb_data, void *data)
{
diff --git a/src/msg.c b/src/msg.c
index 02f812b..0824eb3 100644
--- a/src/msg.c
+++ b/src/msg.c
@@ -164,6 +164,13 @@ struct nlmsghdr *mnl_nlmsg_next(const struct nlmsghdr *nlh, int *len)
return (struct nlmsghdr *)((void *)nlh + mnl_align(nlh->nlmsg_len));
}
+/**
+ * mnl_nlmsg_get_tail - get the ending of the netlink message
+ * @nlh: pointer to netlink message
+ *
+ * This function returns a pointer to the netlink message tail. This is useful
+ * to build a message since we continue adding attribute at the end of it.
+ */
void *mnl_nlmsg_get_tail(const struct nlmsghdr *nlh)
{
return (struct nlmsghdr *)((void *)nlh + mnl_align(nlh->nlmsg_len));