From 78cddab700c3d526e0677b8cfd7c7b9a5fd97e2e Mon Sep 17 00:00:00 2001 From: Pablo Neira Ayuso Date: Wed, 8 Sep 2010 13:45:41 +0200 Subject: doxygen documentation Signed-off-by: Pablo Neira Ayuso --- src/attr.c | 146 ++++++++++++++++++++++++++++++--------------------------- src/callback.c | 41 +++++++++------- src/nlmsg.c | 82 +++++++++++++++++--------------- src/socket.c | 94 ++++++++++++++++++++++++++++--------- 4 files changed, 220 insertions(+), 143 deletions(-) (limited to 'src') diff --git a/src/attr.c b/src/attr.c index d220652..9c17f4d 100644 --- a/src/attr.c +++ b/src/attr.c @@ -12,22 +12,26 @@ #include /* for INT_MAX */ #include -/* - * Netlink Type-Length-Value (TLV) attribute: - * - * |<-- 2 bytes -->|<-- 2 bytes -->|<-- variable -->| - * ------------------------------------------------- - * | length | type | value | - * ------------------------------------------------- - * |<--------- header ------------>|<-- payload --->| +/** + * \defgroup attr Netlink attribute helpers * + * Netlink Type-Length-Value (TLV) attribute: + * \verbatim + |<-- 2 bytes -->|<-- 2 bytes -->|<-- variable -->| + ------------------------------------------------- + | length | type | value | + ------------------------------------------------- + |<--------- header ------------>|<-- payload --->| +\endverbatim * The payload of the Netlink message contains sequences of attributes that are * expressed in TLV format. + * + * @{ */ /** * mnl_attr_get_type - get type of netlink attribute - * @attr: pointer to netlink attribute + * \param attr pointer to netlink attribute * * This function returns the attribute type. */ @@ -38,7 +42,7 @@ uint16_t mnl_attr_get_type(const struct nlattr *attr) /** * mnl_attr_get_len - get length of netlink attribute - * @attr: pointer to netlink attribute + * \param attr pointer to netlink attribute * * This function returns the attribute length that is the attribute header * plus the attribute payload. @@ -50,7 +54,7 @@ uint16_t mnl_attr_get_len(const struct nlattr *attr) /** * mnl_attr_get_payload_len - get the attribute payload-value length - * @attr: pointer to netlink attribute + * \param attr pointer to netlink attribute * * This function returns the attribute payload-value length. */ @@ -71,8 +75,8 @@ void *mnl_attr_get_payload(const struct nlattr *attr) /** * mnl_attr_ok - check if there is room for an attribute in a buffer - * @nattr: attribute that we want to check if there is room for - * @len: remaining bytes in a buffer that contains the attribute + * \param nattr attribute that we want to check if there is room for + * \param len remaining bytes in a buffer that contains the attribute * * This function is used to check that a buffer, which is supposed to contain * an attribute, has enough room for the attribute that it stores, ie. this @@ -82,7 +86,7 @@ void *mnl_attr_get_payload(const struct nlattr *attr) * This function does not set errno in case of error since it is intended * for iterations. Thus, it returns 1 on success and 0 on error. * - * The @len parameter may be negative in the case of malformed messages during + * The len parameter may be negative in the case of malformed messages during * attribute iteration, that is why we use a signed integer. */ int mnl_attr_ok(const struct nlattr *attr, int len) @@ -94,8 +98,8 @@ int mnl_attr_ok(const struct nlattr *attr, int len) /** * mnl_attr_next - get the next attribute in the payload of a netlink message - * @attr: pointer to the current attribute - * @len: length of the remaining bytes in the buffer (passed by reference). + * \param attr pointer to the current attribute + * \param len length of the remaining bytes in the buffer (passed by reference). * * 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 @@ -109,8 +113,8 @@ struct nlattr *mnl_attr_next(const struct nlattr *attr, int *len) /** * mnl_attr_type_valid - check if the attribute type is valid - * @attr: pointer to attribute to be checked - * @max: maximum attribute type + * \param attr pointer to attribute to be checked + * \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 @@ -184,15 +188,6 @@ static int __mnl_attr_validate(const struct nlattr *attr, return 0; } -/** - * mnl_attr_validate - validate netlink attribute (simplified version) - * @attr: pointer to netlink attribute that we want to validate - * @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. - */ static size_t mnl_attr_data_type_len[MNL_TYPE_MAX] = { [MNL_TYPE_U8] = sizeof(uint8_t), [MNL_TYPE_U16] = sizeof(uint16_t), @@ -200,6 +195,15 @@ static size_t mnl_attr_data_type_len[MNL_TYPE_MAX] = { [MNL_TYPE_U64] = sizeof(uint64_t), }; +/** + * mnl_attr_validate - validate netlink attribute (simplified version) + * \param attr pointer to netlink attribute that we want to validate + * \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. + */ int mnl_attr_validate(const struct nlattr *attr, enum mnl_attr_data_type type) { int exp_len; @@ -214,9 +218,9 @@ int mnl_attr_validate(const struct nlattr *attr, enum mnl_attr_data_type type) /** * mnl_attr_validate2 - validate netlink attribute (extended version) - * @attr: pointer to netlink attribute that we want to validate - * @type: attribute type (see enum mnl_attr_data_type) - * @exp_len: expected attribute data size + * \param attr pointer to netlink attribute that we want to validate + * \param type attribute type (see enum mnl_attr_data_type) + * \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, @@ -234,10 +238,10 @@ int mnl_attr_validate2(const struct nlattr *attr, /** * mnl_attr_parse - parse attributes - * @nlh: pointer to netlink message - * @offset: offset to start parsing from (if payload is after any extra header) - * @cb: callback function that is called for each attribute - * @data: pointer to data that is passed to the callback function + * \param nlh pointer to netlink message + * \param offset offset to start parsing from (if payload is after any header) + * \param cb callback function that is called for each attribute + * \param data pointer to data that is passed to the callback function * * This function allows to iterate over the sequence of attributes that compose * the Netlink message. You can then put the attribute in an array as it @@ -264,9 +268,9 @@ int mnl_attr_parse(const struct nlmsghdr *nlh, unsigned int offset, /** * mnl_attr_parse_nested - parse attributes inside a nest - * @nested: pointer to netlink attribute that contains a nest - * @cb: callback function that is called for each attribute in the nest - * @data: pointer to data passed to the callback function + * \param nested pointer to netlink attribute that contains a nest + * \param cb callback function that is called for each attribute in the nest + * \param data pointer to data passed to the callback function * * This function allows to iterate over the sequence of attributes that compose * the Netlink message. You can then put the attribute in an array as it @@ -293,7 +297,7 @@ int mnl_attr_parse_nested(const struct nlattr *nested, /** * mnl_attr_get_u8 - returns 8-bit unsigned integer attribute payload - * @attr: pointer to netlink attribute + * \param attr pointer to netlink attribute * * This function returns the 8-bit value of the attribute payload. */ @@ -304,7 +308,7 @@ uint8_t mnl_attr_get_u8(const struct nlattr *attr) /** * mnl_attr_get_u16 - returns 16-bit unsigned integer attribute payload - * @attr: pointer to netlink attribute + * \param attr pointer to netlink attribute * * This function returns the 16-bit value of the attribute payload. */ @@ -315,7 +319,7 @@ uint16_t mnl_attr_get_u16(const struct nlattr *attr) /** * mnl_attr_get_u32 - returns 32-bit unsigned integer attribute payload - * @attr: pointer to netlink attribute + * \param attr pointer to netlink attribute * * This function returns the 32-bit value of the attribute payload. */ @@ -326,7 +330,7 @@ uint32_t mnl_attr_get_u32(const struct nlattr *attr) /** * mnl_attr_get_u64 - returns 64-bit unsigned integer attribute. - * @attr: pointer to netlink 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 @@ -341,7 +345,7 @@ uint64_t mnl_attr_get_u64(const struct nlattr *attr) /** * mnl_attr_get_str - returns pointer to string attribute. - * @attr: pointer to netlink attribute + * \param attr pointer to netlink attribute * * This function returns the payload of string attribute value. */ @@ -352,10 +356,10 @@ const char *mnl_attr_get_str(const struct nlattr *attr) /** * mnl_attr_put - add an attribute to netlink message - * @nlh: pointer to the netlink message - * @type: netlink attribute type that you want to add - * @len: netlink attribute payload length - * @data: pointer to the data that will be stored by the new attribute + * \param nlh pointer to the netlink message + * \param type netlink attribute type that you want to add + * \param len netlink attribute payload length + * \param data pointer to the data that will be 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. @@ -374,10 +378,10 @@ void mnl_attr_put(struct nlmsghdr *nlh, uint16_t type, /** * 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 + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param len netlink attribute payload size + * \param data 8-bit unsigned 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. @@ -389,9 +393,9 @@ void mnl_attr_put_u8(struct nlmsghdr *nlh, uint16_t type, uint8_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 + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param data 16-bit unsigned 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. @@ -403,9 +407,9 @@ void mnl_attr_put_u16(struct nlmsghdr *nlh, uint16_t type, uint16_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 + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param data 32-bit unsigned 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. @@ -417,9 +421,9 @@ void mnl_attr_put_u32(struct nlmsghdr *nlh, uint16_t type, uint32_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 + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param data 64-bit unsigned 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. @@ -431,9 +435,9 @@ void mnl_attr_put_u64(struct nlmsghdr *nlh, uint16_t type, uint64_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 + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param data pointer to string 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. @@ -445,9 +449,9 @@ void mnl_attr_put_str(struct nlmsghdr *nlh, uint16_t type, const void *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 + * \param nlh pointer to the netlink message + * \param type netlink attribute type + * \param 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. @@ -462,8 +466,8 @@ void mnl_attr_put_str_null(struct nlmsghdr *nlh, uint16_t type, const void *data /** * mnl_attr_nest_start - start an attribute nest - * @nlh: pointer to the netlink message - * @type: netlink attribute type + * \param nlh pointer to the netlink message + * \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 @@ -482,8 +486,8 @@ struct nlattr *mnl_attr_nest_start(struct nlmsghdr *nlh, uint16_t type) /** * mnl_attr_nest_end - end an attribute nest - * @nlh: pointer to the netlink message - * @start: pointer to the attribute nest returned by mnl_attr_nest_start() + * \param nlh pointer to the netlink message + * \param start pointer to the attribute nest returned by mnl_attr_nest_start() * * This function updates the attribute header that identifies the nest. */ @@ -491,3 +495,7 @@ void mnl_attr_nest_end(struct nlmsghdr *nlh, struct nlattr *start) { start->nla_len = mnl_nlmsg_get_payload_tail(nlh) - (void *)start; } + +/** + * @} + */ diff --git a/src/callback.c b/src/callback.c index ded22aa..e1599ff 100644 --- a/src/callback.c +++ b/src/callback.c @@ -44,16 +44,21 @@ static mnl_cb_t default_cb_array[NLMSG_MIN_TYPE] = { [NLMSG_OVERRUN] = mnl_cb_noop, }; +/** + * \defgroup callback Callback helpers + * @{ + */ + /** * mnl_cb_run2 - callback runqueue for netlink messages - * @buf: buffer that contains the netlink messages - * @numbytes: number of bytes stored in the buffer - * @seq: sequence number that we expect to receive - * @portid: Netlink PortID that we expect to receive - * @cb_data: callback handler for data messages - * @data: pointer to data that will be passed to the data callback handler - * @cb_ctl_array: array of custom callback handlers from control messages - * @cb_ctl_array_len: length of the array of custom control callback handlers + * \param buf buffer that contains the netlink messages + * \param numbytes number of bytes stored in the buffer + * \param seq sequence number that we expect to receive + * \param portid Netlink PortID that we expect to receive + * \param cb_data callback handler for data messages + * \param data pointer to data that will be passed to the data callback handler + * \param cb_ctl_array array of custom callback handlers from control messages + * \param cb_ctl_array_len array length of custom control callback handlers * * You can set the cb_ctl_array to NULL if you want to use the default control * callback handlers, in that case, the parameter cb_ctl_array_len is not @@ -62,7 +67,7 @@ static mnl_cb_t default_cb_array[NLMSG_MIN_TYPE] = { * Your callback may return three possible values: * - MNL_CB_ERROR (<=-1): an error has occurred. Stop callback runqueue. * - MNL_CB_STOP (=0): stop callback runqueue. - * - MNL_CB_OK (>=1): no problems has occurred. + * - MNL_CB_OK (>=1): no problem has occurred. * * This function propagates the callback return value. On error, it returns * -1 and errno is explicitly set. If the portID is not the expected, errno @@ -114,12 +119,12 @@ out: /** * mnl_cb_run - callback runqueue for netlink messages (simplified version) - * @buf: buffer that contains the netlink messages - * @numbytes: number of bytes stored in the buffer - * @seq: sequence number that we expect to receive - * @portid: Netlink PortID that we expect to receive - * @cb_data: callback handler for data messages - * @data: pointer to data that will be passed to the data callback handler + * \param buf buffer that contains the netlink messages + * \param numbytes number of bytes stored in the buffer + * \param seq sequence number that we expect to receive + * \param portid Netlink PortID that we expect to receive + * \param cb_data callback handler for data messages + * \param data pointer to data that will be passed to the data callback handler * * This function is like mnl_cb_run2() but it does not allow you to set * the control callback handlers. @@ -127,7 +132,7 @@ out: * Your callback may return three possible values: * - MNL_CB_ERROR (<=-1): an error has occurred. Stop callback runqueue. * - MNL_CB_STOP (=0): stop callback runqueue. - * - MNL_CB_OK (>=1): no problems has occurred. + * - MNL_CB_OK (>=1): no problems has occurred. * * This function propagates the callback return value. */ @@ -136,3 +141,7 @@ int mnl_cb_run(const char *buf, size_t numbytes, unsigned int seq, { return mnl_cb_run2(buf, numbytes, seq, portid, cb_data, data, NULL, 0); } + +/** + * @} + */ diff --git a/src/nlmsg.c b/src/nlmsg.c index 9b2f457..af08671 100644 --- a/src/nlmsg.c +++ b/src/nlmsg.c @@ -13,34 +13,38 @@ #include #include -/* - * Netlink message: - * - * |<----------------- 4 bytes ------------------->| - * |<----- 2 bytes ------>|<------- 2 bytes ------>| +/** + * \defgroup nlmsg Netlink message helpers * - * |-----------------------------------------------| - * | Message length (including header) | - * |-----------------------------------------------| - * | Message type | Message flags | - * |-----------------------------------------------| - * | Message sequence number | - * |-----------------------------------------------| - * | Netlink PortID | - * |-----------------------------------------------| - * | | - * . Payload . - * |_______________________________________________| + * Netlink message: + * \verbatim + |<----------------- 4 bytes ------------------->| + |<----- 2 bytes ------>|<------- 2 bytes ------>| + |-----------------------------------------------| + | Message length (including header) | + |-----------------------------------------------| + | Message type | Message flags | + |-----------------------------------------------| + | Message sequence number | + |-----------------------------------------------| + | Netlink PortID | + |-----------------------------------------------| + | | + . Payload . + |_______________________________________________| +\endverbatim * * There is usually an extra header after the the Netlink header (at the * beginning of the payload). This extra header is specific of the Netlink * subsystem. After this extra header, it comes the sequence of attributes * that are expressed in Type-Length-Value (TLV) format. + * + * @{ */ /** * mnl_nlmsg_size - calculate the size of Netlink message (without alignment) - * @len: length of the Netlink payload + * \param len length of the Netlink payload * * This function returns the size of a netlink message (header plus payload) * without alignment. @@ -52,7 +56,7 @@ size_t mnl_nlmsg_size(size_t len) /** * mnl_nlmsg_aligned_size - calculate the aligned size of Netlink messages - * @len: length of the Netlink payload + * \param len length of the Netlink payload * * This function returns the size of a netlink message (header plus payload) * with alignment. @@ -64,7 +68,7 @@ size_t mnl_nlmsg_aligned_size(size_t len) /** * mnl_nlmsg_get_payload_len - get the length of the Netlink payload - * @nlh: pointer to the header of the Netlink message + * \param nlh pointer to the header of the Netlink message * * This function returns the Length of the netlink payload, ie. the length * of the full message minus the size of the Netlink header. @@ -76,7 +80,7 @@ size_t mnl_nlmsg_get_payload_len(const struct nlmsghdr *nlh) /** * mnl_nlmsg_put_header - reserve and prepare room for Netlink header - * @buf: memory already allocated to store the Netlink header + * \param buf memory already allocated to store the Netlink header * * This function sets to zero the room that is required to put the Netlink * header in the memory buffer passed as parameter. This function also @@ -95,8 +99,8 @@ struct nlmsghdr *mnl_nlmsg_put_header(void *buf) /** * mnl_nlmsg_put_extra_header - reserve and prepare room for an extra header - * @nlh: pointer to Netlink header - * @size: size of the extra header that we want to put + * \param nlh pointer to Netlink header + * \param size size of the extra header that we want to put * * This function sets to zero the room that is required to put the extra * header after the initial Netlink header. This function also increases @@ -114,7 +118,7 @@ void *mnl_nlmsg_put_extra_header(struct nlmsghdr *nlh, size_t size) /** * mnl_nlmsg_get_payload - get a pointer to the payload of the netlink message - * @nlh: pointer to a netlink header + * \param nlh pointer to a netlink header * * This function returns a pointer to the payload of the netlink message. */ @@ -125,8 +129,8 @@ void *mnl_nlmsg_get_payload(const struct nlmsghdr *nlh) /** * mnl_nlmsg_get_payload_offset - get a pointer to the payload of the message - * @nlh: pointer to a netlink header - * @offset: offset to the payload of the attributes TLV set + * \param nlh pointer to a netlink header + * \param offset offset to the payload of the attributes TLV set * * This function returns a pointer to the payload of the netlink message plus * a given offset. @@ -138,8 +142,8 @@ void *mnl_nlmsg_get_payload_offset(const struct nlmsghdr *nlh, size_t offset) /** * mnl_nlmsg_ok - check a there is room for netlink message - * @nlh: netlink message that we want to check - * @len: remaining bytes in a buffer that contains the netlink message + * \param nlh netlink message that we want to check + * \param len remaining bytes in a buffer that contains the netlink message * * This function is used to check that a buffer that contains a netlink * message has enough room for the netlink message that it stores, ie. this @@ -149,7 +153,7 @@ void *mnl_nlmsg_get_payload_offset(const struct nlmsghdr *nlh, size_t offset) * This function does not set errno in case of error since it is intended * for iterations. Thus, it returns 1 on success and 0 on error. * - * The @len parameter may become negative in malformed messages during message + * The len parameter may become negative in malformed messages during message * iteration, that is why we use a signed integer. */ int mnl_nlmsg_ok(const struct nlmsghdr *nlh, int len) @@ -161,8 +165,8 @@ int mnl_nlmsg_ok(const struct nlmsghdr *nlh, int len) /** * mnl_nlmsg_next - get the next netlink message in a multipart message - * @nlh: current netlink message that we are handling - * @len: length of the remaining bytes in the buffer (passed by reference). + * \param nlh current netlink message that we are handling + * \param len length of the remaining bytes in the buffer (passed by reference). * * This function returns a pointer to the next netlink message that is part * of a multi-part netlink message. Netlink can batch several messages into @@ -180,7 +184,7 @@ struct nlmsghdr *mnl_nlmsg_next(const struct nlmsghdr *nlh, int *len) /** * mnl_nlmsg_get_payload_tail - get the ending of the netlink message - * @nlh: pointer to netlink message + * \param 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 attributes at the end of the @@ -193,8 +197,8 @@ void *mnl_nlmsg_get_payload_tail(const struct nlmsghdr *nlh) /** * mnl_nlmsg_seq_ok - perform sequence tracking - * @nlh: current netlink message that we are handling - * @seq: last sequence number used to send a message + * \param nlh current netlink message that we are handling + * \param seq last sequence number used to send a message * * This functions returns 1 if the sequence tracking is fulfilled, otherwise * 0 is returned. We skip the tracking for netlink messages whose sequence @@ -212,8 +216,8 @@ int mnl_nlmsg_seq_ok(const struct nlmsghdr *nlh, unsigned int seq) /** * mnl_nlmsg_portid_ok - perform portID origin check - * @nlh: current netlink message that we are handling - * @seq: netlink portid that we want to check + * \param nlh current netlink message that we are handling + * \param seq netlink portid that we want to check * * This functions return 1 if the origin is fulfilled, otherwise * 0 is returned. We skip the tracking for netlink message whose portID @@ -231,7 +235,7 @@ int mnl_nlmsg_portid_ok(const struct nlmsghdr *nlh, unsigned int portid) /** * mnl_nlmsg_fprintf - print netlink message to file - * @nlh: pointer to netlink message that we want to print + * \param nlh pointer to netlink message that we want to print * * This function prints the netlink header to a file. This function may be * useful for debugging purposes. @@ -262,3 +266,7 @@ void mnl_nlmsg_fprintf(FILE *fd, const struct nlmsghdr *nlh) isalnum(b[i+3]) ? b[i+3] : 0); } } + +/** + * @} + */ diff --git a/src/socket.c b/src/socket.c index cf8f251..de1424c 100644 --- a/src/socket.c +++ b/src/socket.c @@ -15,14 +15,62 @@ #include #include +/** + * \mainpage + * + * libmnl is a minimalistic user-space library oriented to Netlink developers. + * There are a lot of common tasks in parsing, validating, constructing of + * both the Netlink header and TLVs that are repetitive and easy to get wrong. + * This library aims to provide simple helpers that allows you to avoid + * re-inventing the wheel in common Netlink tasks. + * + * The acronim libmnl stands for LIBrary Minimalistic NetLink. + * + * (temporary) libmnl homepage is: + * http://1984.lsi.us.es/projects/libmnl/ + * + * \section features Main Features + * - Small: the shared library requires around 30KB in a x86-based computer. + * - Simple: this library avoids complex abstractions that tend to hide Netlink + * details. It avoids elaborated object-oriented infrastructure and complex + * callback-based workflow. + * - Easy to use: the library simplifies the work for Netlink-wise developers. + * It provides functions to make socket handling, message building, + * validating, parsing, and sequence tracking, easier. + * - Easy to re-use: you can use this library to build your own abstraction + * layer upon this library, if you want to provide another library that + * hides Netlink details to your users. + * - Decoupling: the interdependency of the main bricks that compose this + * library is reduced, ie. the library provides many helpers but the + * programmer is not forced to use them. + * + * \section Dependencies + * You have to install the Linux kernel headers that you want to use to develop + * your application. Moreover, this library requires that you have some basics + * on Netlink. + * + * \section scm Git Tree + * The current development version of libmnl can be accessed at: + * http://1984.lsi.us.es/git/?p=libmnl/.git;a=summary + * + * \section using Using libmnl + * You can access several examples files under examples/ in the libmnl source + * code tree. + */ + struct mnl_socket { int fd; struct sockaddr_nl addr; }; +/** + * \defgroup socket Netlink socket helpers + * @{ + */ + /** * mnl_socket_get_fd - obtain file descriptor from netlink socket - * @nl: netlink socket obtained via mnl_socket_open() + * \param nl netlink socket obtained via mnl_socket_open() * * This function returns the file descriptor of a given netlink socket. */ @@ -33,7 +81,7 @@ int mnl_socket_get_fd(const struct mnl_socket *nl) /** * mnl_socket_get_portid - obtain Netlink PortID from netlink socket - * @nl: netlink socket obtained via mnl_socket_open() + * \param nl netlink socket obtained via mnl_socket_open() * * This function returns the Netlink PortID of a given netlink socket. * It's a common mistake to assume that this PortID equals the process ID @@ -47,7 +95,7 @@ unsigned int mnl_socket_get_portid(const struct mnl_socket *nl) /** * mnl_socket_open - open a netlink socket - * @unit: the netlink socket bus ID (see NETLINK_* constants) + * \param unit the netlink socket bus ID (see NETLINK_* constants) * * On error, it returns -1 and errno is appropriately set. Otherwise, it * returns a valid pointer to the mnl_socket structure. @@ -71,9 +119,9 @@ struct mnl_socket *mnl_socket_open(int bus) /** * mnl_socket_bind - bind netlink socket - * @nl: netlink socket obtained via mnl_socket_open() - * @groups: the group of message you're interested in - * @pid: the port ID you want to use (use zero for automatic selection) + * \param nl netlink socket obtained via mnl_socket_open() + * \param groups the group of message you're interested in + * \param pid the port ID you want to use (use zero for automatic selection) * * On error, this function returns -1 and errno is appropriately set. On * success, 0 is returned. You can use MNL_SOCKET_AUTOPID which is 0 for @@ -110,9 +158,9 @@ int mnl_socket_bind(struct mnl_socket *nl, int groups, int pid) /** * mnl_socket_sendto - send a netlink message of a certain size - * @nl: netlink socket obtained via mnl_socket_open() - * @buf: buffer containing the netlink message to be sent - * @bufsiz: number of bytes in the buffer that you want to send + * \param nl netlink socket obtained via mnl_socket_open() + * \param buf buffer containing the netlink message to be sent + * \param bufsiz number of bytes in the buffer that you want to send * * On error, it returns -1 and errno is appropriately set. Otherwise, it * returns the number of bytes sent. @@ -128,9 +176,9 @@ int mnl_socket_sendto(const struct mnl_socket *nl, const void *buf, size_t len) /** * mnl_socket_recvfrom - receive a netlink message - * @nl: netlink socket obtained via mnl_socket_open() - * @buf: buffer that you want to use to store the netlink message - * @bufsiz: size of the buffer passed to store the netlink message + * \param nl netlink socket obtained via mnl_socket_open() + * \param buf buffer that you want to use to store the netlink message + * \param bufsiz size of the buffer passed to store the netlink message * * On error, it returns -1 and errno is appropriately set. If errno is set * to ENOSPC, it means that the buffer that you have passed to store the @@ -171,7 +219,7 @@ int mnl_socket_recvfrom(const struct mnl_socket *nl, void *buf, size_t bufsiz) /** * mnl_socket_close - close a given netlink socket - * @nl: netlink socket obtained via mnl_socket_open() + * \param nl netlink socket obtained via mnl_socket_open() * * On error, this function returns -1 and errno is appropriately set. * On success, it returns 0. @@ -186,10 +234,10 @@ int mnl_socket_close(struct mnl_socket *nl) /** * mnl_socket_setsockopt - set Netlink socket option - * @nl: netlink socket obtained via mnl_socket_open() - * @type: type of Netlink socket options - * @buf: the buffer that contains the data about this option - * @len: the size of the buffer passed + * \param nl netlink socket obtained via mnl_socket_open() + * \param type type of Netlink socket options + * \param buf the buffer that contains the data about this option + * \param len the size of the buffer passed * * This function allows you to set some Netlink socket option. As of writing * this, the existing options are: @@ -217,10 +265,10 @@ int mnl_socket_setsockopt(const struct mnl_socket *nl, int type, /** * mnl_socket_getsockopt - get a Netlink socket option - * @nl: netlink socket obtained via mnl_socket_open() - * @type: type of Netlink socket options - * @buf: pointer to the buffer to store the value of this option - * @len: size of the information written in the buffer + * \param nl netlink socket obtained via mnl_socket_open() + * \param type type of Netlink socket options + * \param buf pointer to the buffer to store the value of this option + * \param len size of the information written in the buffer * * On error, this function returns -1 and errno is appropriately set. */ @@ -229,3 +277,7 @@ int mnl_socket_getsockopt(const struct mnl_socket *nl, int type, { return getsockopt(nl->fd, SOL_NETLINK, type, buf, len); } + +/** + * @} + */ -- cgit v1.2.3