register_protocol

   $class->register_protocol( $proto )

May be called by a subclass implementing a Netlink protocol. If so, then any object constructed using a known protocol on this base class will be automatically reblessed into the appropriate package.

new

   $sock = IO::Socket::Netlink->new( %args )

Creates a new "IO::Socket::Netlink" object.

The recognised arguments are:

Protocol => INT

The netlink protocol. This is a required argument.

Pid => INT

Socket identifier (usually the process identifier)

Groups => INT

32bit bitmask of multicast groups to join

sockpid

   $pid = $sock->sockpid

Returns the socket identifier

sockgroups

   $groups = $sock->sockgroups

Returns the 32bit bitmask of multicast groups

new_message

   $msg = $sock->new_message( %args )

Returns a new message object containing the given arguments. The named arguments are in fact read as an list of key/value pairs, not a hash, so order is significant. The basic "nlmsg_*" keys should come first, followed by any required by the inner level header.

For more detail, see the "MESSAGE OBJECTS" section below.

new_request

   $msg = $sock->new_request( %args )

A convenience wrapper around "new_message" which sets the "NLM_F_REQUEST" flag on the returned message.

new_command

   $sock->new_command( %args )

As "new_request", but may use a different class for messages. This is for such netlink protocols as "TASKSTATS", which uses a different set of message attributes for userland-to-kernel commands, as for kernel-to-userland event messages.

send_nlmsg

   $sock->send_nlmsg( $message )

Sends the given message object to the kernel. $message should be a message object, constructed using the socket's "new_message" factory method.

recv_nlmsg

   $sock->recv_nlmsg( $message, $maxlen )

Receives a single message from the kernel. The $message parameter should be a variable, which will contain the new message object when this method returns successfully.

Sometimes the kernel will respond multiple messages in reply to just one. If this may be the case, see instead "recv_nlmsgs".

This method returns success or failure depending only on the result of the underlying socket "recv" call. If a message was successfully received it returns true, even if that message contains an error. To detect the error, see the "nlerr_error" accessor.

recv_nlmsgs

   $sock->recv_nlmsgs( \@messages, $maxlen )

Receives message from the kernel. If the first message received has the "NLM_F_MULTI" flag, then messages will be collected up until the final "NLMSG_DONE" which indicates the end of the list. Each message is pushed into the @messages array (which is not cleared initially), excluding the final "NLMSG_DONE".

This method returns success or failure depending only on the result of the underlying socket "recv" call or calls. If any calls fails then the method will return false. If messages were successfully received it returns true, even if a message contains an error. To detect the error, see the "nlerr_error" accessor.

$messageclass->is_header( %args )

Called by a subclass of the message class, this class method declares that messages of this particular type contain a message header. The four required fields of %args define how this behaves:

• data => STRING

  Gives the name of the accessor method on its parent class which contains the data buffer for the header. Normally this would be "nlmsg" for direct subclasses of the base message class, but further subclasses would need to use the trailing data buffer accessor of their parent class.

• fields => ARRAY

  Reference to an array of definitions for the fields, in the order returned by the pack function or expected by the unpack function. A new accessor method will be created for each.

  Each field item should either be an ARRAY reference containing the following structure, or a plain scalar denoting simply its name

   [ $name, $type, %opts ]
      

  The $type defines the default value of the attribute, and determines how it will be printed by the "STRING" method:

• pack => CODE
• unpack => CODE

  References to code that, respectively, packs a list of field values into a packed string value, or unpacks a packed string value back out into a list of values.

When the header is declared, the base class's method named by "data" will be overridden by generated code. This overridden method unpacks the values of the fields into accessors when it is set, or packs the accessors into a value when queried.

This arrangement can be continued by further subclasses which implement further levels of wrapping, if the pack and unpack functions implement a data tail area; that is, the pack function takes an extra string buffer and the unpack function returns one, for extra bytes after the header itself. The last named field will then contain this buffer.

$messageclass->is_subclassed_by_type

Called by a subclass of the message class, this class method declares that messages are further subclassed according to the value of their "nlmsg_type". This will override the "nlmsg_type" accessor to re-"bless" the object into its declared subclass according to the types declared to the generated "register_nlmsg_type" method.

For example

 package IO::Socket::Netlink::SomeProto::_Message;
 use base qw( IO::Socket::Netlink::_Message );
 __PACKAGE__->is_subclassed_by_type;
 package IO::Socket::Netlink::SomeProto::_InfoMessage;
 __PACKAGE__->register_nlmsg_type( 123 );
 ...

At this point, if a message is constructed with this type number, either by code calling "new_message", or received from the socket, it will be automatically reblessed to the appropriate class.

This feature is intended for use by netlink protocols where different message types have different stucture types.

$messageclass->has_nlattrs( $fieldname, %attrs )

Called by a subclass of the message class, this class method is intended to be used by subclass authors to declare the attributes the message protocol understands. The data declared here is used by the "nlattrs" method.

$fieldname should be the name of an existing method on the object class; this method will be used to obtain or set the data field containing the attributes (typically this will be the trailing message body). %attrs should be a hash, mapping symbolic names of fields into their typeid and data format. Each entry should be of the form

 $name => [ $typeid, $datatype ]

When the "attrs" method is packing attributes into the message body, it will read attributes by $name and encode them using the given $datatype to store in the body by $typeid. When it is unpacking attributes from the body, it will use the $typeid to decode the data, and return it in a hash key of the given $name.

The following standard definitions exist for $datatype:

• u8

  An unsigned 8-bit number

• u16

  An unsigned 16-bit number

• u32

  An unsigned 32-bit number

• u64

  An unsigned 64-bit number

• asciiz

  A NULL-terminated string of ASCII text

• raw

  No encoding or decoding will take place; the value contains the raw byte buffer

• nested

  The buffer itself contains more attributes in the same schema. These will be taken or returned in a HASH reference.

A subclass can define new data types by providing methods called "pack_nlattr_$datatype" and "unpack_nlattr_$datatype" which will be used to encode or decode the attribute value into a string buffer.

$message->nlattrs( \%newattrs )

Sets the message body field by encoding the attributes given by %newattrs, keyed by name, into Netlink attribute values, by using the definitions declared by the subclass's "has_nlattrs" method.

\%attrs = $message->nlattrs

Returns the decoded attributes from the message body field.

$value = $message->get_nlattr( $name )

Returns the decoded value of a single attribute from the message body field. Similar to

 $value = $message->nlattrs->{$name}

except it does not incur the extra cost of decoding the other attribute values that remain unused.

$message->change_nlattrs( %newvalues )

Changes the stored values of the given attributes in the message body field. Similar to

 $message->nlattrs( { %{ $message->nlattrs }, %newvalues } );

except it does not incur the extra cost of decoding and reencoding the unmodified attribute values.

A value of "undef" may be assigned to delete an attribute.

The following accessors are provided for debugging purposes

$str = $message->nlmsg_type_string

Renders the message type into a readable string form. Subclasses may wish to override this method to return other strings they recognise, or call to "SUPER" if they don't.

$str = $message->nlmsg_flags_string

Renders the flags into a readable string form. Each flag present is named, joined by "|" characters.

$str = $message->nlmsg_string

Intended for subclasses to override, to include more of their own information about nested headers.

$str = $message->STRING

$str = "$message"

Returns a human-readable string form of the message, giving details of the values of the fields. Provided primarily for debugging purposes.

$message->nlerr_error

Accessor for the error value from the kernel. This will be a system error value such used by $!. This accessor also exists on non-error messages, but returns false. This makes it easy to test for an error after "recv_nlmsg":

 $sock->recv_nlmsg( my $message, 2**15 ) or die "Cannot recv - $!";
 ( $! = $message->nlerr_error ) and die "Received NLMSG_ERROR - $!";

$message->nlerr_msg

Accessor for the original netlink message header that invoked the error. This value may be unpacked using "unpack_nlmsghdr".