.TH "nlmsg" 3 "Version 1.0.5" "libmnl" \" -*- nroff -*- .ad l .nh .SH NAME nlmsg \- Netlink message helpers .SH SYNOPSIS .br .PP .SS "Functions" .in +1c .ti -1c .RI "size_t \fBmnl_nlmsg_size\fP (size_t len)" .br .ti -1c .RI "size_t \fBmnl_nlmsg_get_payload_len\fP (const struct nlmsghdr *nlh)" .br .ti -1c .RI "struct nlmsghdr * \fBmnl_nlmsg_put_header\fP (void *buf)" .br .ti -1c .RI "void * \fBmnl_nlmsg_put_extra_header\fP (struct nlmsghdr *nlh, size_t size)" .br .ti -1c .RI "void * \fBmnl_nlmsg_get_payload\fP (const struct nlmsghdr *nlh)" .br .ti -1c .RI "void * \fBmnl_nlmsg_get_payload_offset\fP (const struct nlmsghdr *nlh, size_t offset)" .br .ti -1c .RI "bool \fBmnl_nlmsg_ok\fP (const struct nlmsghdr *nlh, int len)" .br .ti -1c .RI "struct nlmsghdr * \fBmnl_nlmsg_next\fP (const struct nlmsghdr *nlh, int *len)" .br .ti -1c .RI "void * \fBmnl_nlmsg_get_payload_tail\fP (const struct nlmsghdr *nlh)" .br .ti -1c .RI "bool \fBmnl_nlmsg_seq_ok\fP (const struct nlmsghdr *nlh, unsigned int seq)" .br .ti -1c .RI "bool \fBmnl_nlmsg_portid_ok\fP (const struct nlmsghdr *nlh, unsigned int portid)" .br .ti -1c .RI "void \fBmnl_nlmsg_fprintf\fP (FILE *fd, const void *data, size_t datalen, size_t extra_header_size)" .br .in -1c .SH "Detailed Description" .PP Netlink message: .PP .nf |<----------------- 4 bytes ------------------->| |<----- 2 bytes ------>|<------- 2 bytes ------>| |-----------------------------------------------| | Message length (including header) | |-----------------------------------------------| | Message type | Message flags | |-----------------------------------------------| | Message sequence number | |-----------------------------------------------| | Netlink PortID | |-----------------------------------------------| | | \&. Payload \&. |_______________________________________________| .fi .PP .PP 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\&. .SH "Function Documentation" .PP .SS "void mnl_nlmsg_fprintf (FILE * fd, const void * data, size_t datalen, size_t extra_header_size)" mnl_nlmsg_fprintf - print netlink message to file .PP \fBParameters\fP .RS 4 \fIfd\fP pointer to file type .br \fIdata\fP pointer to the buffer that contains messages to be printed .br \fIdatalen\fP length of data stored in the buffer .br \fIextra_header_size\fP size of the extra header (if any) .RE .PP This function prints the netlink header to a file handle\&. It may be useful for debugging purposes\&. One example of the output is the following: .PP .PP .nf ---------------- ------------------ | 0000000040 | | message length | | 00016 | R-A- | | type | flags | | 1289148991 | | sequence number| | 0000000000 | | port ID | ---------------- ------------------ | 00 00 00 00 | | extra header | | 00 00 00 00 | | extra header | | 01 00 00 00 | | extra header | | 01 00 00 00 | | extra header | |00008|--|00003| |len |flags| type| | 65 74 68 30 | | data | e t h 0 ---------------- ------------------ .fi .PP .PP This example above shows the netlink message that is send to kernel-space to set up the link interface eth0\&. The netlink and attribute header data are displayed in base 10 whereas the extra header and the attribute payload are expressed in base 16\&. The possible flags in the netlink header are: .PP .IP "\(bu" 2 R, that indicates that NLM_F_REQUEST is set\&. .IP "\(bu" 2 M, that indicates that NLM_F_MULTI is set\&. .IP "\(bu" 2 A, that indicates that NLM_F_ACK is set\&. .IP "\(bu" 2 E, that indicates that NLM_F_ECHO is set\&. .PP .PP The lack of one flag is displayed with '-'\&. On the other hand, the possible attribute flags available are: .PP .IP "\(bu" 2 N, that indicates that NLA_F_NESTED is set\&. .IP "\(bu" 2 B, that indicates that NLA_F_NET_BYTEORDER is set\&. .PP .PP Definition at line \fB360\fP of file \fBnlmsg\&.c\fP\&. .SS "void * mnl_nlmsg_get_payload (const struct nlmsghdr * nlh)" mnl_nlmsg_get_payload - get a pointer to the payload of the netlink message .PP \fBParameters\fP .RS 4 \fInlh\fP pointer to a netlink header .RE .PP This function returns a pointer to the payload of the netlink message\&. .PP Definition at line \fB117\fP of file \fBnlmsg\&.c\fP\&. .SS "size_t mnl_nlmsg_get_payload_len (const struct nlmsghdr * nlh)" mnl_nlmsg_get_payload_len - get the length of the Netlink payload .PP \fBParameters\fP .RS 4 \fInlh\fP pointer to the header of the Netlink message .RE .PP This function returns the Length of the netlink payload, ie\&. the length of the full message minus the size of the Netlink header\&. .PP Definition at line \fB66\fP of file \fBnlmsg\&.c\fP\&. .SS "void * mnl_nlmsg_get_payload_offset (const struct nlmsghdr * nlh, size_t offset)" mnl_nlmsg_get_payload_offset - get a pointer to the payload of the message .PP \fBParameters\fP .RS 4 \fInlh\fP pointer to a netlink header .br \fIoffset\fP offset to the payload of the attributes TLV set .RE .PP This function returns a pointer to the payload of the netlink message plus a given offset\&. .PP Definition at line \fB130\fP of file \fBnlmsg\&.c\fP\&. .SS "void * mnl_nlmsg_get_payload_tail (const struct nlmsghdr * nlh)" mnl_nlmsg_get_payload_tail - get the ending of the netlink message .PP \fBParameters\fP .RS 4 \fInlh\fP pointer to netlink message .RE .PP 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 message\&. .PP Definition at line \fB187\fP of file \fBnlmsg\&.c\fP\&. .SS "struct nlmsghdr * mnl_nlmsg_next (const struct nlmsghdr * nlh, int * len)" mnl_nlmsg_next - get the next netlink message in a multipart message .PP \fBParameters\fP .RS 4 \fInlh\fP current netlink message that we are handling .br \fIlen\fP length of the remaining bytes in the buffer (passed by reference)\&. .RE .PP 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 one buffer so that the receiver has to iterate over the whole set of Netlink messages\&. .PP You have to use \fBmnl_nlmsg_ok()\fP to check if the next Netlink message is valid\&. .PP Definition at line \fB172\fP of file \fBnlmsg\&.c\fP\&. .SS "bool mnl_nlmsg_ok (const struct nlmsghdr * nlh, int len)" mnl_nlmsg_ok - check a there is room for netlink message .PP \fBParameters\fP .RS 4 \fInlh\fP netlink message that we want to check .br \fIlen\fP remaining bytes in a buffer that contains the netlink message .RE .PP 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 function can be used to verify that a netlink message is not malformed nor truncated\&. .PP 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\&. .PP The len parameter may become negative in malformed messages during message iteration, that is why we use a signed integer\&. .PP Definition at line \fB152\fP of file \fBnlmsg\&.c\fP\&. .SS "bool mnl_nlmsg_portid_ok (const struct nlmsghdr * nlh, unsigned int portid)" mnl_nlmsg_portid_ok - perform portID origin check .PP \fBParameters\fP .RS 4 \fInlh\fP current netlink message that we are handling .br \fIportid\fP netlink portid that we want to check .RE .PP This functions returns true if the origin is fulfilled, otherwise false is returned\&. We skip the tracking for netlink message whose portID is zero since it is reserved for event-based kernel notifications\&. On the other hand, if portid is set but the message PortID is not (i\&.e\&. this is an event message coming from kernel-space), then we also skip the tracking\&. This approach is good if we use the same socket to send commands to kernel-space (that we want to track) and to listen to events (that we do not track)\&. .PP Definition at line \fB226\fP of file \fBnlmsg\&.c\fP\&. .SS "void * mnl_nlmsg_put_extra_header (struct nlmsghdr * nlh, size_t size)" mnl_nlmsg_put_extra_header - reserve and prepare room for an extra header .PP \fBParameters\fP .RS 4 \fInlh\fP pointer to Netlink header .br \fIsize\fP size of the extra header that we want to put .RE .PP This function sets to zero the room that is required to put the extra header after the initial Netlink header\&. This function also increases the nlmsg_len field\&. You have to invoke \fBmnl_nlmsg_put_header()\fP before you call this function\&. This function returns a pointer to the extra header\&. .PP Definition at line \fB101\fP of file \fBnlmsg\&.c\fP\&. .SS "struct nlmsghdr * mnl_nlmsg_put_header (void * buf)" mnl_nlmsg_put_header - reserve and prepare room for Netlink header .PP \fBParameters\fP .RS 4 \fIbuf\fP memory already allocated to store the Netlink header .RE .PP 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 initializes the nlmsg_len field to the size of the Netlink header\&. This function returns a pointer to the Netlink header structure\&. .PP Definition at line \fB80\fP of file \fBnlmsg\&.c\fP\&. .SS "bool mnl_nlmsg_seq_ok (const struct nlmsghdr * nlh, unsigned int seq)" mnl_nlmsg_seq_ok - perform sequence tracking .PP \fBParameters\fP .RS 4 \fInlh\fP current netlink message that we are handling .br \fIseq\fP last sequence number used to send a message .RE .PP This functions returns true if the sequence tracking is fulfilled, otherwise false is returned\&. We skip the tracking for netlink messages whose sequence number is zero since it is usually reserved for event-based kernel notifications\&. On the other hand, if seq is set but the message sequence number is not set (i\&.e\&. this is an event message coming from kernel-space), then we also skip the tracking\&. This approach is good if we use the same socket to send commands to kernel-space (that we want to track) and to listen to events (that we do not track)\&. .PP Definition at line \fB206\fP of file \fBnlmsg\&.c\fP\&. .SS "size_t mnl_nlmsg_size (size_t len)" mnl_nlmsg_size - calculate the size of Netlink message (without alignment) .PP \fBParameters\fP .RS 4 \fIlen\fP length of the Netlink payload .RE .PP This function returns the size of a netlink message (header plus payload) without alignment\&. .PP Definition at line \fB54\fP of file \fBnlmsg\&.c\fP\&. .SH "Author" .PP Generated automatically by Doxygen for libmnl from the source code\&.