1IO::Socket::Netlink(3)User Contributed Perl DocumentationIO::Socket::Netlink(3)
2
3
4

NAME

6       "IO::Socket::Netlink" - Object interface to "PF_NETLINK" domain sockets
7

SYNOPSIS

9        use Socket::Netlink;
10        use IO::Socket::Netlink;
11
12        my $sock = IO::Socket::Netlink->new( Protocol => 0 ) or die "socket: $!";
13
14        $sock->send_nlmsg( $sock->new_request(
15           nlmsg_type  => 18,
16           nlmsg_flags => NLM_F_DUMP,
17           nlmsg       => "\0\0\0\0\0\0\0\0",
18        ) ) or die "send: $!";
19
20        $sock->recv_nlmsg( my $message, 65536 ) or die "recv: $!";
21
22        printf "Received type=%d flags=%x:\n%v02x\n",
23           $message->nlmsg_type, $message->nlmsg_flags, $message->nlmsg;
24

DESCRIPTION

26       This module provides an object interface to "PF_NETLINK" sockets on
27       Linux, by building on top of the IO::Socket class. While useful on its
28       own, it is intended itself to serve as a base class, for particular
29       netlink protocols to extend.
30

CLASS METHODS

32   register_protocol
33          $class->register_protocol( $proto )
34
35       May be called by a subclass implementing a Netlink protocol. If so,
36       then any object constructed using a known protocol on this base class
37       will be automatically reblessed into the appropriate package.
38

CONSTRUCTOR

40   new
41          $sock = IO::Socket::Netlink->new( %args )
42
43       Creates a new "IO::Socket::Netlink" object.
44
45       The recognised arguments are:
46
47       Protocol => INT
48               The netlink protocol. This is a required argument.
49
50       Pid => INT
51               Socket identifier (usually the process identifier)
52
53       Groups => INT
54               32bit bitmask of multicast groups to join
55

METHODS

57   sockpid
58          $pid = $sock->sockpid
59
60       Returns the socket identifier
61
62   sockgroups
63          $groups = $sock->sockgroups
64
65       Returns the 32bit bitmask of multicast groups
66
67   new_message
68          $msg = $sock->new_message( %args )
69
70       Returns a new message object containing the given arguments. The named
71       arguments are in fact read as an list of key/value pairs, not a hash,
72       so order is significant. The basic "nlmsg_*" keys should come first,
73       followed by any required by the inner level header.
74
75       For more detail, see the "MESSAGE OBJECTS" section below.
76
77   new_request
78          $msg = $sock->new_request( %args )
79
80       A convenience wrapper around "new_message" which sets the
81       "NLM_F_REQUEST" flag on the returned message.
82
83   new_command
84          $sock->new_command( %args )
85
86       As "new_request", but may use a different class for messages. This is
87       for such netlink protocols as "TASKSTATS", which uses a different set
88       of message attributes for userland-to-kernel commands, as for kernel-
89       to-userland event messages.
90
91   send_nlmsg
92          $sock->send_nlmsg( $message )
93
94       Sends the given message object to the kernel. $message should be a
95       message object, constructed using the socket's "new_message" factory
96       method.
97
98   recv_nlmsg
99          $sock->recv_nlmsg( $message, $maxlen )
100
101       Receives a single message from the kernel. The $message parameter
102       should be a variable, which will contain the new message object when
103       this method returns successfully.
104
105       Sometimes the kernel will respond multiple messages in reply to just
106       one. If this may be the case, see instead "recv_nlmsgs".
107
108       This method returns success or failure depending only on the result of
109       the underlying socket "recv" call. If a message was successfully
110       received it returns true, even if that message contains an error. To
111       detect the error, see the "nlerr_error" accessor.
112
113   recv_nlmsgs
114          $sock->recv_nlmsgs( \@messages, $maxlen )
115
116       Receives message from the kernel. If the first message received has the
117       "NLM_F_MULTI" flag, then messages will be collected up until the final
118       "NLMSG_DONE" which indicates the end of the list. Each message is
119       pushed into the @messages array (which is not cleared initially),
120       excluding the final "NLMSG_DONE".
121
122       This method returns success or failure depending only on the result of
123       the underlying socket "recv" call or calls. If any calls fails then the
124       method will return false. If messages were successfully received it
125       returns true, even if a message contains an error. To detect the error,
126       see the "nlerr_error" accessor.
127

MESSAGE OBJECTS

129       Netlink messages are passed in to "send_nlmsg" and returned by
130       "recv_nlmsg" and "recv_nlmsgs" in the form of objects, which wrap the
131       protocol headers.  These objects are not directly constructed; instead
132       you should use the "new_message" method on the socket to build a new
133       message to send.
134
135       These objects exist also to wrap higher-level protocol fields, for
136       messages in some particular netlink protocol. A subclass of
137       "IO::Socket::Netlink" would likely use its own subclass of message
138       object; extra fields may exist on these objects.
139
140       The following accessors may be used to set or obtain the fields in the
141       toplevel "nlmsghdr" structure:
142
143       •   $message->nlmsg_type
144
145       •   $message->nlmsg_flags
146
147       •   $message->nlmsg_seq
148
149       •   $message->nlmsg_pid
150
151           Set or obtain the fields in the "nlmsghdr" structure.
152
153       •   $message->nlmsg
154
155           Set or obtain the packed message body. This method is intended to
156           be overridden by specific protocol implementations, to pack or
157           unpack their own structure type.
158
159       Many Netlink-based protocols use standard message headers with
160       attribute bodies. Messages may start with structure layouts containing
161       standard fields, optionally followed by a sequence of one or more
162       attributes in a standard format. Each attribute is an ID number and a
163       value.
164
165       Because this class is intended to be subclassed by specific Netlink
166       protocol implementations, a number of class methods exist to declare
167       metadata about the protocol to assist generating the code required to
168       support it. A message class can declare its header format, which
169       defines what extra accessor fields will be created, and functions to
170       pack and unpack the fields to or from the message body. It can also
171       declare its mapping of attribute names, ID numbers, and data types. The
172       message class will then support automatic encoding and decoding of
173       named attributes to or from the buffer.
174
175   $messageclass->is_header( %args )
176       Called by a subclass of the message class, this class method declares
177       that messages of this particular type contain a message header. The
178       four required fields of %args define how this behaves:
179
180       •   data => STRING
181
182           Gives the name of the accessor method on its parent class which
183           contains the data buffer for the header. Normally this would be
184           "nlmsg" for direct subclasses of the base message class, but
185           further subclasses would need to use the trailing data buffer
186           accessor of their parent class.
187
188       •   fields => ARRAY
189
190           Reference to an array of definitions for the fields, in the order
191           returned by the pack function or expected by the unpack function. A
192           new accessor method will be created for each.
193
194           Each field item should either be an ARRAY reference containing the
195           following structure, or a plain scalar denoting simply its name
196
197            [ $name, $type, %opts ]
198
199           The $type defines the default value of the attribute, and
200           determines how it will be printed by the "STRING" method:
201
202           •   decimal
203
204               Default 0, printed with printf "%d"
205
206           •   hex
207
208               Default 0, printed with printf "%x"
209
210           •   bytes
211
212               Default "", printed with printf "%v02x"
213
214           •   string
215
216               Default "", printed with printf "%s"
217
218           The following options are recognised:
219
220           default => SCALAR
221                   A value to set for the field when the message header is
222                   packed, if no other value has been provided.
223
224           Fields defined simply by name are given the type of "decimal" with
225           a default value of 0, and no other options.
226
227       •   pack => CODE
228
229       •   unpack => CODE
230
231           References to code that, respectively, packs a list of field values
232           into a packed string value, or unpacks a packed string value back
233           out into a list of values.
234
235       When the header is declared, the base class's method named by "data"
236       will be overridden by generated code. This overridden method unpacks
237       the values of the fields into accessors when it is set, or packs the
238       accessors into a value when queried.
239
240       This arrangement can be continued by further subclasses which implement
241       further levels of wrapping, if the pack and unpack functions implement
242       a data tail area; that is, the pack function takes an extra string
243       buffer and the unpack function returns one, for extra bytes after the
244       header itself. The last named field will then contain this buffer.
245
246   $messageclass->is_subclassed_by_type
247       Called by a subclass of the message class, this class method declares
248       that messages are further subclassed according to the value of their
249       "nlmsg_type".  This will override the "nlmsg_type" accessor to
250       re-"bless" the object into its declared subclass according to the types
251       declared to the generated "register_nlmsg_type" method.
252
253       For example
254
255        package IO::Socket::Netlink::SomeProto::_Message;
256        use base qw( IO::Socket::Netlink::_Message );
257
258        __PACKAGE__->is_subclassed_by_type;
259
260        package IO::Socket::Netlink::SomeProto::_InfoMessage;
261
262        __PACKAGE__->register_nlmsg_type( 123 );
263
264        ...
265
266       At this point, if a message is constructed with this type number,
267       either by code calling "new_message", or received from the socket, it
268       will be automatically reblessed to the appropriate class.
269
270       This feature is intended for use by netlink protocols where different
271       message types have different stucture types.
272
273   $messageclass->has_nlattrs( $fieldname, %attrs )
274       Called by a subclass of the message class, this class method is
275       intended to be used by subclass authors to declare the attributes the
276       message protocol understands. The data declared here is used by the
277       "nlattrs" method.
278
279       $fieldname should be the name of an existing method on the object
280       class; this method will be used to obtain or set the data field
281       containing the attributes (typically this will be the trailing message
282       body). %attrs should be a hash, mapping symbolic names of fields into
283       their typeid and data format. Each entry should be of the form
284
285        $name => [ $typeid, $datatype ]
286
287       When the "attrs" method is packing attributes into the message body, it
288       will read attributes by $name and encode them using the given $datatype
289       to store in the body by $typeid. When it is unpacking attributes from
290       the body, it will use the $typeid to decode the data, and return it in
291       a hash key of the given $name.
292
293       The following standard definitions exist for $datatype:
294
295       •   u8
296
297           An unsigned 8-bit number
298
299       •   u16
300
301           An unsigned 16-bit number
302
303       •   u32
304
305           An unsigned 32-bit number
306
307       •   u64
308
309           An unsigned 64-bit number
310
311       •   asciiz
312
313           A NULL-terminated string of ASCII text
314
315       •   raw
316
317           No encoding or decoding will take place; the value contains the raw
318           byte buffer
319
320       •   nested
321
322           The buffer itself contains more attributes in the same schema.
323           These will be taken or returned in a HASH reference.
324
325       A subclass can define new data types by providing methods called
326       "pack_nlattr_$datatype" and "unpack_nlattr_$datatype" which will be
327       used to encode or decode the attribute value into a string buffer.
328
329   $message->nlattrs( \%newattrs )
330       Sets the message body field by encoding the attributes given by
331       %newattrs, keyed by name, into Netlink attribute values, by using the
332       definitions declared by the subclass's "has_nlattrs" method.
333
334   \%attrs = $message->nlattrs
335       Returns the decoded attributes from the message body field.
336
337   $value = $message->get_nlattr( $name )
338       Returns the decoded value of a single attribute from the message body
339       field.  Similar to
340
341        $value = $message->nlattrs->{$name}
342
343       except it does not incur the extra cost of decoding the other attribute
344       values that remain unused.
345
346   $message->change_nlattrs( %newvalues )
347       Changes the stored values of the given attributes in the message body
348       field.  Similar to
349
350        $message->nlattrs( { %{ $message->nlattrs }, %newvalues } );
351
352       except it does not incur the extra cost of decoding and reencoding the
353       unmodified attribute values.
354
355       A value of "undef" may be assigned to delete an attribute.
356
357       The following accessors are provided for debugging purposes
358
359   $str = $message->nlmsg_type_string
360       Renders the message type into a readable string form. Subclasses may
361       wish to override this method to return other strings they recognise, or
362       call to "SUPER" if they don't.
363
364   $str = $message->nlmsg_flags_string
365       Renders the flags into a readable string form. Each flag present is
366       named, joined by "|" characters.
367
368   $str = $message->nlmsg_string
369       Intended for subclasses to override, to include more of their own
370       information about nested headers.
371
372   $str = $message->STRING
373   $str = "$message"
374       Returns a human-readable string form of the message, giving details of
375       the values of the fields. Provided primarily for debugging purposes.
376

ERROR MESSAGE OBJECTS

378       If a message object has its "nlmsg_type" field set to "NLMSG_ERROR"
379       then the object will be reblessed into a subclass that encapsulates the
380       error message.
381
382   $message->nlerr_error
383       Accessor for the error value from the kernel. This will be a system
384       error value such used by $!. This accessor also exists on non-error
385       messages, but returns false. This makes it easy to test for an error
386       after "recv_nlmsg":
387
388        $sock->recv_nlmsg( my $message, 2**15 ) or die "Cannot recv - $!";
389        ( $! = $message->nlerr_error ) and die "Received NLMSG_ERROR - $!";
390
391   $message->nlerr_msg
392       Accessor for the original netlink message header that invoked the
393       error. This value may be unpacked using "unpack_nlmsghdr".
394

SEE ALSO

396       •   Socket::Netlink - interface to Linux's "PF_NETLINK" socket family
397

AUTHOR

399       Paul Evans <leonerd@leonerd.org.uk>
400
401
402
403perl v5.36.0                      2023-01-20            IO::Socket::Netlink(3)
Impressum