libnl 3.10.0
Message Construction & Parsing

Netlink Message Construction/Parsing Interface More...

Topics

 Attributes
 Netlink Attributes Construction/Parsing Interface
 

Macros

#define NL_AUTO_PORT   0
 Will cause the netlink port to be set to the port assigned to the netlink icoket ust before sending the message off.
 
#define NL_AUTO_SEQ   0
 May be used to refer to a sequence number which should be automatically set just before sending the message off.
 

Netlink Message Type Translations

char * nl_nlmsgtype2str (int type, char *buf, size_t size)
 
int nl_str2nlmsgtype (const char *name)
 

Size Calculations

int nlmsg_size (int payload)
 Calculates size of netlink message based on payload length.
 
int nlmsg_total_size (int payload)
 Calculates size of netlink message including padding based on payload length.
 
int nlmsg_padlen (int payload)
 Size of padding that needs to be added at end of message.
 

Access to Message Payload

void * nlmsg_data (const struct nlmsghdr *nlh)
 Return pointer to message payload.
 
void * nlmsg_tail (const struct nlmsghdr *nlh)
 
int nlmsg_datalen (const struct nlmsghdr *nlh)
 Return length of message payload.
 

Attribute Access

struct nlattr * nlmsg_attrdata (const struct nlmsghdr *nlh, int hdrlen)
 head of attributes data
 
int nlmsg_attrlen (const struct nlmsghdr *nlh, int hdrlen)
 length of attributes data
 

Message Parsing

int nlmsg_valid_hdr (const struct nlmsghdr *nlh, int hdrlen)
 
int nlmsg_ok (const struct nlmsghdr *nlh, int remaining)
 check if the netlink message fits into the remaining bytes
 
struct nlmsghdr * nlmsg_next (struct nlmsghdr *nlh, int *remaining)
 next netlink message in message stream
 
int nlmsg_parse (struct nlmsghdr *nlh, int hdrlen, struct nlattr *tb[], int maxtype, const struct nla_policy *policy)
 parse attributes of a netlink message
 
struct nlattr * nlmsg_find_attr (struct nlmsghdr *nlh, int hdrlen, int attrtype)
 nlmsg_find_attr - find a specific attribute in a netlink message
 
int nlmsg_validate (struct nlmsghdr *nlh, int hdrlen, int maxtype, const struct nla_policy *policy)
 nlmsg_validate - validate a netlink message including attributes
 

Message Building/Access

struct nl_msg * nlmsg_alloc (void)
 Allocate a new netlink message with the default maximum payload size.
 
struct nl_msg * nlmsg_alloc_size (size_t max)
 Allocate a new netlink message with maximum payload size specified.
 
struct nl_msg * nlmsg_inherit (struct nlmsghdr *hdr)
 Allocate a new netlink message and inherit netlink message header.
 
struct nl_msg * nlmsg_alloc_simple (int nlmsgtype, int flags)
 Allocate a new netlink message.
 
void nlmsg_set_default_size (size_t max)
 Set the default maximum message payload size for allocated messages.
 
struct nl_msg * nlmsg_convert (struct nlmsghdr *hdr)
 Convert a netlink message received from a netlink socket to a nl_msg.
 
void * nlmsg_reserve (struct nl_msg *n, size_t len, int pad)
 Reserve room for additional data in a netlink message.
 
int nlmsg_append (struct nl_msg *n, void *data, size_t len, int pad)
 Append data to tail of a netlink message.
 
int nlmsg_expand (struct nl_msg *n, size_t newlen)
 Expand maximum payload size of a netlink message.
 
struct nlmsghdr * nlmsg_put (struct nl_msg *n, uint32_t pid, uint32_t seq, int type, int payload, int flags)
 Add a netlink message header to a netlink message.
 
struct nlmsghdr * nlmsg_hdr (struct nl_msg *n)
 Return actual netlink message.
 
void nlmsg_get (struct nl_msg *msg)
 Acquire a reference on a netlink message.
 
void nlmsg_free (struct nl_msg *msg)
 Release a reference from an netlink message.
 

Attributes

void nlmsg_set_proto (struct nl_msg *msg, int protocol)
 
int nlmsg_get_proto (struct nl_msg *msg)
 
size_t nlmsg_get_max_size (struct nl_msg *msg)
 
void nlmsg_set_src (struct nl_msg *msg, struct sockaddr_nl *addr)
 
struct sockaddr_nl * nlmsg_get_src (struct nl_msg *msg)
 
void nlmsg_set_dst (struct nl_msg *msg, struct sockaddr_nl *addr)
 
struct sockaddr_nl * nlmsg_get_dst (struct nl_msg *msg)
 
void nlmsg_set_creds (struct nl_msg *msg, struct ucred *creds)
 
struct ucred * nlmsg_get_creds (struct nl_msg *msg)
 

Netlink Message Flags Translations

char * nl_nlmsg_flags2str (int flags, char *buf, size_t len)
 

Direct Parsing

int nl_msg_parse (struct nl_msg *msg, void(*cb)(struct nl_object *, void *), void *arg)
 

Dumping

void nl_msg_dump (struct nl_msg *msg, FILE *ofd)
 Dump message in human readable format to file descriptor.
 

Iterators

#define nlmsg_for_each_attr(pos, nlh, hdrlen, rem)
 Iterate over a stream of attributes in a message.
 
#define nlmsg_for_each(pos, head, len)
 Iterate over a stream of messages.
 
#define nlmsg_for_each_msg(pos, head, len, rem)    nlmsg_for_each(pos, head, len)
 

Detailed Description

Netlink Message Construction/Parsing Interface

Related sections in the development guide:

Header

#include <netlink/msg.h>

Macro Definition Documentation

◆ NL_AUTO_PORT

#define NL_AUTO_PORT   0

Will cause the netlink port to be set to the port assigned to the netlink icoket ust before sending the message off.

Note
Requires the use of nl_send_auto()!

Definition at line 29 of file msg.h.

Referenced by nl_complete_msg().

◆ NL_AUTO_SEQ

#define NL_AUTO_SEQ   0

May be used to refer to a sequence number which should be automatically set just before sending the message off.

Note
Requires the use of nl_send_auto()!

Definition at line 40 of file msg.h.

Referenced by nl_complete_msg(), nlmsg_alloc_simple(), and rtnl_link_change().

◆ nlmsg_for_each_attr

#define nlmsg_for_each_attr ( pos,
nlh,
hdrlen,
rem )
Value:
nla_for_each_attr(pos, nlmsg_attrdata(nlh, hdrlen), \
nlmsg_attrlen(nlh, hdrlen), rem)
#define nla_for_each_attr(pos, head, len, rem)
Iterate over a stream of attributes.
Definition attr.h:312
int nlmsg_attrlen(const struct nlmsghdr *, int)
length of attributes data
Definition msg.c:157
struct nlattr * nlmsg_attrdata(const struct nlmsghdr *, int)
head of attributes data
Definition msg.c:146

Iterate over a stream of attributes in a message.

Parameters
posloop counter, set to current attribute
nlhnetlink message header
hdrlenlength of family header
reminitialized to len, holds bytes currently remaining in stream

Definition at line 119 of file msg.h.

◆ nlmsg_for_each

#define nlmsg_for_each ( pos,
head,
len )
Value:
for (int rem = len, pos = head; \
nlmsg_ok(pos, rem); \
pos = nlmsg_next(pos, &rem))
struct nlmsghdr * nlmsg_next(struct nlmsghdr *, int *)
next netlink message in message stream
Definition msg.c:200

Iterate over a stream of messages.

Parameters
posloop counter, set to current message
headhead of message stream
lenlength of message stream

Definition at line 129 of file msg.h.

◆ nlmsg_for_each_msg

#define nlmsg_for_each_msg ( pos,
head,
len,
rem )    nlmsg_for_each(pos, head, len)

Definition at line 134 of file msg.h.

Function Documentation

◆ nlmsg_size()

int nlmsg_size ( int payload)

Calculates size of netlink message based on payload length.

Parameters
payloadLength of payload
Returns
size of netlink message without padding.

Definition at line 57 of file msg.c.

◆ nlmsg_total_size()

int nlmsg_total_size ( int payload)

Calculates size of netlink message including padding based on payload length.

Parameters
payloadLength of payload

This function is idential to nlmsg_size() + nlmsg_padlen().

Returns
Size of netlink message including padding.

Definition at line 75 of file msg.c.

Referenced by nlmsg_padlen(), and nlmsg_set_default_size().

+ Here is the caller graph for this function:

◆ nlmsg_padlen()

int nlmsg_padlen ( int payload)

Size of padding that needs to be added at end of message.

Parameters
payloadLength of payload

Calculates the number of bytes of padding which is required to be added to the end of the message to ensure that the next netlink message header begins properly aligned to NLMSG_ALIGNTO.

Returns
Number of bytes of padding needed.

Definition at line 90 of file msg.c.

References nlmsg_total_size().

+ Here is the call graph for this function:

◆ nlmsg_data()

void * nlmsg_data ( const struct nlmsghdr * nlh)

Return pointer to message payload.

Parameters
nlhNetlink message header
Returns
Pointer to start of message payload.

Definition at line 108 of file msg.c.

Referenced by genlmsg_hdr(), genlmsg_parse(), genlmsg_put(), genlmsg_valid_hdr(), genlmsg_validate(), nfnlmsg_family(), nfnlmsg_res_id(), nla_put(), nla_put_nested(), nla_reserve(), and nlmsg_attrdata().

+ Here is the caller graph for this function:

◆ nlmsg_tail()

void * nlmsg_tail ( const struct nlmsghdr * nlh)

Definition at line 113 of file msg.c.

◆ nlmsg_datalen()

int nlmsg_datalen ( const struct nlmsghdr * nlh)

Return length of message payload.

Parameters
nlhNetlink message header
Returns
Length of message payload in bytes.

Definition at line 124 of file msg.c.

Referenced by nla_put_nested().

+ Here is the caller graph for this function:

◆ nlmsg_attrdata()

struct nlattr * nlmsg_attrdata ( const struct nlmsghdr * nlh,
int hdrlen )

head of attributes data

Parameters
nlhnetlink message header
hdrlenlength of family specific header

Definition at line 146 of file msg.c.

References nlmsg_data().

Referenced by nlmsg_find_attr(), nlmsg_parse(), and nlmsg_validate().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nlmsg_attrlen()

int nlmsg_attrlen ( const struct nlmsghdr * nlh,
int hdrlen )

length of attributes data

Parameters
nlhnetlink message header
hdrlenlength of family specific header

Definition at line 157 of file msg.c.

Referenced by nlmsg_find_attr(), nlmsg_parse(), and nlmsg_validate().

+ Here is the caller graph for this function:

◆ nlmsg_valid_hdr()

int nlmsg_valid_hdr ( const struct nlmsghdr * nlh,
int hdrlen )

Definition at line 169 of file msg.c.

◆ nlmsg_ok()

int nlmsg_ok ( const struct nlmsghdr * nlh,
int remaining )

check if the netlink message fits into the remaining bytes

Parameters
nlhnetlink message header
remainingnumber of bytes remaining in message stream

Definition at line 185 of file msg.c.

◆ nlmsg_next()

struct nlmsghdr * nlmsg_next ( struct nlmsghdr * nlh,
int * remaining )

next netlink message in message stream

Parameters
nlhnetlink message header
remainingnumber of bytes remaining in message stream
Returns
the next netlink message in the message stream and decrements remaining by the size of the current message.

Definition at line 200 of file msg.c.

◆ nlmsg_parse()

int nlmsg_parse ( struct nlmsghdr * nlh,
int hdrlen,
struct nlattr * tb[],
int maxtype,
const struct nla_policy * policy )

parse attributes of a netlink message

Parameters
nlhnetlink message header
hdrlenlength of family specific header
tbdestination array with maxtype+1 elements
maxtypemaximum attribute type to be expected
policyvalidation policy

See nla_parse()

Definition at line 219 of file msg.c.

References nla_parse(), nlmsg_attrdata(), and nlmsg_attrlen().

+ Here is the call graph for this function:

◆ nlmsg_find_attr()

struct nlattr * nlmsg_find_attr ( struct nlmsghdr * nlh,
int hdrlen,
int attrtype )

nlmsg_find_attr - find a specific attribute in a netlink message

Parameters
nlhnetlink message header
hdrlenlength of familiy specific header
attrtypetype of attribute to look for

Returns the first attribute which matches the specified type.

Definition at line 237 of file msg.c.

References nla_find(), nlmsg_attrdata(), and nlmsg_attrlen().

+ Here is the call graph for this function:

◆ nlmsg_validate()

int nlmsg_validate ( struct nlmsghdr * nlh,
int hdrlen,
int maxtype,
const struct nla_policy * policy )

nlmsg_validate - validate a netlink message including attributes

Parameters
nlhnetlinket message header
hdrlenlength of familiy specific header
maxtypemaximum attribute type to be expected
policyvalidation policy

Definition at line 250 of file msg.c.

References nla_validate(), nlmsg_attrdata(), and nlmsg_attrlen().

+ Here is the call graph for this function:

◆ nlmsg_alloc()

struct nl_msg * nlmsg_alloc ( void )

Allocate a new netlink message with the default maximum payload size.

Allocates a new netlink message without any further payload. The maximum payload size defaults to PAGESIZE or as otherwise specified with nlmsg_set_default_size().

Returns
Newly allocated netlink message or NULL.

Definition at line 305 of file msg.c.

Referenced by nlmsg_inherit(), and rtnl_neightbl_build_change_request().

+ Here is the caller graph for this function:

◆ nlmsg_alloc_size()

struct nl_msg * nlmsg_alloc_size ( size_t max)

Allocate a new netlink message with maximum payload size specified.

Definition at line 313 of file msg.c.

◆ nlmsg_inherit()

struct nl_msg * nlmsg_inherit ( struct nlmsghdr * hdr)

Allocate a new netlink message and inherit netlink message header.

Parameters
hdrNetlink message header template

Allocates a new netlink message and inherits the original message header. If hdr is not NULL it will be used as a template for the netlink message header, otherwise the header is left blank.

Returns
Newly allocated netlink message or NULL

Definition at line 328 of file msg.c.

References nlmsg_alloc().

Referenced by nlmsg_alloc_simple().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nlmsg_alloc_simple()

struct nl_msg * nlmsg_alloc_simple ( int nlmsgtype,
int flags )

Allocate a new netlink message.

Parameters
nlmsgtypeNetlink message type
flagsMessage flags.
Returns
Newly allocated netlink message or NULL.

Definition at line 352 of file msg.c.

References NL_AUTO_SEQ, and nlmsg_inherit().

Referenced by flnl_lookup_build_request(), nfnlmsg_alloc_simple(), nl_send_simple(), rtnl_class_build_delete_request(), rtnl_link_build_delete_request(), rtnl_link_build_get_request(), rtnl_neightbl_build_change_request(), and rtnl_qdisc_build_delete_request().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nlmsg_set_default_size()

void nlmsg_set_default_size ( size_t max)

Set the default maximum message payload size for allocated messages.

Parameters
maxSize of payload in bytes.

Definition at line 373 of file msg.c.

References nlmsg_total_size().

+ Here is the call graph for this function:

◆ nlmsg_convert()

struct nl_msg * nlmsg_convert ( struct nlmsghdr * hdr)

Convert a netlink message received from a netlink socket to a nl_msg.

Parameters
hdrNetlink message received from netlink socket.

Allocates a new netlink message and copies all of the data pointed to by hdr into the new message object.

Returns
Newly allocated netlink message or NULL.

Definition at line 393 of file msg.c.

◆ nlmsg_reserve()

void * nlmsg_reserve ( struct nl_msg * n,
size_t len,
int pad )

Reserve room for additional data in a netlink message.

Parameters
nnetlink message
lenlength of additional data to reserve room for
padnumber of bytes to align data to

Reserves room for additional data at the tail of the an existing netlink message. Eventual padding required will be zeroed out.

Returns
Pointer to start of additional data tailroom or NULL.

Definition at line 418 of file msg.c.

Referenced by nlmsg_append(), and nlmsg_put().

+ Here is the caller graph for this function:

◆ nlmsg_append()

int nlmsg_append ( struct nl_msg * n,
void * data,
size_t len,
int pad )

Append data to tail of a netlink message.

Parameters
nnetlink message
datadata to add
lenlength of data
padNumber of bytes to align data to.

Extends the netlink message as needed and appends the data of given length to the message.

Returns
0 on success or a negative error code

Definition at line 456 of file msg.c.

References nlmsg_reserve().

Referenced by flnl_lookup_build_request(), nl_send_simple(), rtnl_class_build_delete_request(), rtnl_link_build_delete_request(), rtnl_link_build_get_request(), rtnl_neightbl_build_change_request(), and rtnl_qdisc_build_delete_request().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nlmsg_expand()

int nlmsg_expand ( struct nl_msg * n,
size_t newlen )

Expand maximum payload size of a netlink message.

Parameters
nNetlink message.
newlenNew maximum payload size.

Reallocates the payload section of a netlink message and increases the maximum payload size of the message.

Note
Any pointers pointing to old payload block will be stale and need to be refetched. Therfore, do not expand while constructing nested attributes or while reserved data blocks are held.
Returns
0 on success or a negative error code.

Definition at line 484 of file msg.c.

◆ nlmsg_put()

struct nlmsghdr * nlmsg_put ( struct nl_msg * n,
uint32_t pid,
uint32_t seq,
int type,
int payload,
int flags )

Add a netlink message header to a netlink message.

Parameters
nnetlink message
pidnetlink process id or NL_AUTO_PID
seqsequence number of message or NL_AUTO_SEQ
typemessage type
payloadlength of message payload
flagsmessage flags

Adds or overwrites the netlink message header in an existing message object. If payload is greater-than zero additional room will be reserved, f.e. for family specific headers. It can be accesed via nlmsg_data().

Returns
A pointer to the netlink message header or NULL.

Definition at line 517 of file msg.c.

References nlmsg_reserve().

Referenced by genlmsg_put(), and nfnlmsg_put().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nlmsg_hdr()

struct nlmsghdr * nlmsg_hdr ( struct nl_msg * n)

Return actual netlink message.

Parameters
nnetlink message

Returns the actual netlink message casted to the type of the netlink message header.

Returns
A pointer to the netlink message.

Definition at line 550 of file msg.c.

Referenced by genl_handle_msg(), nl_cache_parse_and_add(), nl_complete_msg(), nl_msg_dump(), and nl_send().

+ Here is the caller graph for this function:

◆ nlmsg_get()

void nlmsg_get ( struct nl_msg * msg)

Acquire a reference on a netlink message.

Parameters
msgmessage to acquire reference from

Definition at line 559 of file msg.c.

◆ nlmsg_free()

void nlmsg_free ( struct nl_msg * msg)

Release a reference from an netlink message.

Parameters
msgmessage to release reference from

Frees memory after the last reference has been released.

Definition at line 572 of file msg.c.

Referenced by flnl_lookup(), flnl_lookup_build_request(), nfnlmsg_alloc_simple(), nl_send_simple(), nl_send_sync(), rtnl_addr_add(), rtnl_addr_delete(), rtnl_class_build_delete_request(), rtnl_neigh_add(), rtnl_neigh_delete(), rtnl_neightbl_build_change_request(), rtnl_neightbl_change(), rtnl_qdisc_build_delete_request(), rtnl_rule_add(), and rtnl_rule_delete().

+ Here is the caller graph for this function:

◆ nlmsg_set_proto()

void nlmsg_set_proto ( struct nl_msg * msg,
int protocol )

Definition at line 598 of file msg.c.

◆ nlmsg_get_proto()

int nlmsg_get_proto ( struct nl_msg * msg)

Definition at line 603 of file msg.c.

◆ nlmsg_get_max_size()

size_t nlmsg_get_max_size ( struct nl_msg * msg)

Definition at line 608 of file msg.c.

◆ nlmsg_set_src()

void nlmsg_set_src ( struct nl_msg * msg,
struct sockaddr_nl * addr )

Definition at line 613 of file msg.c.

◆ nlmsg_get_src()

struct sockaddr_nl * nlmsg_get_src ( struct nl_msg * msg)

Definition at line 618 of file msg.c.

◆ nlmsg_set_dst()

void nlmsg_set_dst ( struct nl_msg * msg,
struct sockaddr_nl * addr )

Definition at line 623 of file msg.c.

◆ nlmsg_get_dst()

struct sockaddr_nl * nlmsg_get_dst ( struct nl_msg * msg)

Definition at line 628 of file msg.c.

◆ nlmsg_set_creds()

void nlmsg_set_creds ( struct nl_msg * msg,
struct ucred * creds )

Definition at line 633 of file msg.c.

◆ nlmsg_get_creds()

struct ucred * nlmsg_get_creds ( struct nl_msg * msg)

Definition at line 639 of file msg.c.

◆ nl_nlmsgtype2str()

char * nl_nlmsgtype2str ( int type,
char * buf,
size_t size )

Definition at line 660 of file msg.c.

◆ nl_str2nlmsgtype()

int nl_str2nlmsgtype ( const char * name)

Definition at line 666 of file msg.c.

◆ nl_nlmsg_flags2str()

char * nl_nlmsg_flags2str ( int flags,
char * buf,
size_t len )

Definition at line 678 of file msg.c.

◆ nl_msg_parse()

int nl_msg_parse ( struct nl_msg * msg,
void(*)(struct nl_object *, void *) cb,
void * arg )

Definition at line 734 of file msg.c.

◆ nl_msg_dump()

void nl_msg_dump ( struct nl_msg * msg,
FILE * ofd )

Dump message in human readable format to file descriptor.

Parameters
msgMessage to print
ofdFile descriptor.

Definition at line 985 of file msg.c.

References nlmsg_hdr().

+ Here is the call graph for this function: