1IO::Socket::Netlink(3)User Contributed Perl DocumentationIO::Socket::Netlink(3)
2
6 "IO::Socket::Netlink" - Object interface to "PF_NETLINK" domain sockets
7
9 use Socket::Netlink;
10 use IO::Socket::Netlink;
11 my $sock = IO::Socket::Netlink->new( Protocol => 0 ) or die "socket: $!";
13 $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 $sock->recv_nlmsg( my $message, 65536 ) or die "recv: $!";
21 printf "Received type=%d flags=%x:\n%v02x\n",
23 $message->nlmsg_type, $message->nlmsg_flags, $message->nlmsg;
24
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
32 register_protocol
33 $class->register_protocol( $proto )
34 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
40 new
41 $sock = IO::Socket::Netlink->new( %args )
42 Creates a new "IO::Socket::Netlink" object.
44 The recognised arguments are:
46 Protocol => INT
48 The netlink protocol. This is a required argument.
49 Pid => INT
51 Socket identifier (usually the process identifier)
52 Groups => INT
54 32bit bitmask of multicast groups to join
55
57 sockpid
58 $pid = $sock->sockpid
59 Returns the socket identifier
61 sockgroups
63 $groups = $sock->sockgroups
64 Returns the 32bit bitmask of multicast groups
66 new_message
68 $msg = $sock->new_message( %args )
69 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 For more detail, see the "MESSAGE OBJECTS" section below.
76 new_request
78 $msg = $sock->new_request( %args )
79 A convenience wrapper around "new_message" which sets the
81 "NLM_F_REQUEST" flag on the returned message.
82 new_command
84 $sock->new_command( %args )
85 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 send_nlmsg
92 $sock->send_nlmsg( $message )
93 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 recv_nlmsg
99 $sock->recv_nlmsg( $message, $maxlen )
100 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 Sometimes the kernel will respond multiple messages in reply to just
106 one. If this may be the case, see instead "recv_nlmsgs".
107 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 recv_nlmsgs
114 $sock->recv_nlmsgs( \@messages, $maxlen )
115 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 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
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 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 The following accessors may be used to set or obtain the fields in the
141 toplevel "nlmsghdr" structure:
142 • $message->nlmsg_type
144 • $message->nlmsg_flags
146 • $message->nlmsg_seq
148 • $message->nlmsg_pid
150 Set or obtain the fields in the "nlmsghdr" structure.
152 • $message->nlmsg
154 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 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 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 $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 • data => STRING
181 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 • fields => ARRAY
189 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 Each field item should either be an ARRAY reference containing the
195 following structure, or a plain scalar denoting simply its name
196 [ $name, $type, %opts ]
198 The $type defines the default value of the attribute, and
200 determines how it will be printed by the "STRING" method:
201 • decimal
203 Default 0, printed with printf "%d"
205 • hex
207 Default 0, printed with printf "%x"
209 • bytes
211 Default "", printed with printf "%v02x"
213 • string
215 Default "", printed with printf "%s"
217 The following options are recognised:
219 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 Fields defined simply by name are given the type of "decimal" with
225 a default value of 0, and no other options.
226 • pack => CODE
228 • unpack => CODE
230 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 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 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 $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 For example
254 package IO::Socket::Netlink::SomeProto::_Message;
256 use base qw( IO::Socket::Netlink::_Message );
257 __PACKAGE__->is_subclassed_by_type;
259 package IO::Socket::Netlink::SomeProto::_InfoMessage;
261 __PACKAGE__->register_nlmsg_type( 123 );
263 ...
265 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 This feature is intended for use by netlink protocols where different
271 message types have different stucture types.
272 $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 $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 $name => [ $typeid, $datatype ]
286 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 The following standard definitions exist for $datatype:
294 • u8
296 An unsigned 8-bit number
298 • u16
300 An unsigned 16-bit number
302 • u32
304 An unsigned 32-bit number
306 • u64
308 An unsigned 64-bit number
310 • asciiz
312 A NULL-terminated string of ASCII text
314 • raw
316 No encoding or decoding will take place; the value contains the raw
318 byte buffer
319 • nested
321 The buffer itself contains more attributes in the same schema.
323 These will be taken or returned in a HASH reference.
324 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 $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 \%attrs = $message->nlattrs
335 Returns the decoded attributes from the message body field.
336 $value = $message->get_nlattr( $name )
338 Returns the decoded value of a single attribute from the message body
339 field. Similar to
340 $value = $message->nlattrs->{$name}
342 except it does not incur the extra cost of decoding the other attribute
344 values that remain unused.
345 $message->change_nlattrs( %newvalues )
347 Changes the stored values of the given attributes in the message body
348 field. Similar to
349 $message->nlattrs( { %{ $message->nlattrs }, %newvalues } );
351 except it does not incur the extra cost of decoding and reencoding the
353 unmodified attribute values.
354 A value of "undef" may be assigned to delete an attribute.
356 The following accessors are provided for debugging purposes
358 $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 $str = $message->nlmsg_flags_string
365 Renders the flags into a readable string form. Each flag present is
366 named, joined by "|" characters.
367 $str = $message->nlmsg_string
369 Intended for subclasses to override, to include more of their own
370 information about nested headers.
371 $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
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 $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 $sock->recv_nlmsg( my $message, 2**15 ) or die "Cannot recv - $!";
389 ( $! = $message->nlerr_error ) and die "Received NLMSG_ERROR - $!";
390 $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
396 • Socket::Netlink - interface to Linux's "PF_NETLINK" socket family
397
399 Paul Evans <leonerd@leonerd.org.uk>
400perl v5.32.1 2021-01-27 IO::Socket::Netlink(3)