File Coverage

blib/lib/Socket/Netlink.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             # You may distribute under the terms of either the GNU General Public License
2             # or the Artistic License (the same terms as Perl itself)
3             #
4             # (C) Paul Evans, 2010 -- leonerd@leonerd.org.uk
5              
6             package Socket::Netlink;
7              
8 10     10   131356 use strict;
  10         25  
  10         489  
9 10     10   52 use warnings;
  10         14  
  10         290  
10              
11 10     10   60 use Carp;
  10         19  
  10         874  
12              
13             our $VERSION = '0.04';
14              
15 10     10   60 use Exporter 'import';
  10         15  
  10         2572  
16             our @EXPORT_OK = qw(
17             pack_sockaddr_nl unpack_sockaddr_nl
18             pack_nlmsghdr unpack_nlmsghdr
19             pack_nlmsgerr unpack_nlmsgerr
20             pack_nlattrs unpack_nlattrs
21             );
22              
23             require XSLoader;
24             XSLoader::load( __PACKAGE__, $VERSION );
25              
26             =head1 NAME
27              
28             C - interface to Linux's C socket family
29              
30             =head1 SYNOPSIS
31              
32             use Socket;
33             use Socket::Netlink qw( :DEFAULT pack_nlmsghdr unpack_nlmsghdr );
34              
35             socket( my $sock, PF_NETLINK, SOCK_RAW, 0 ) or die "socket: $!";
36              
37             send( $sock, pack_nlmsghdr( 18, NLM_F_REQUEST|NLM_F_DUMP, 0, 0,
38             "\0\0\0\0\0\0\0\0" ), 0 )
39             or die "send: $!";
40              
41             recv( $sock, my $buffer, 65536, 0 ) or die "recv: $!";
42              
43             printf "Received type=%d flags=%x:\n%v02x\n",
44             ( unpack_nlmsghdr( $buffer ) )[ 0, 1, 4 ];
45              
46             =head1 DESCRIPTION
47              
48             This module contains the low-level constants and structure handling functions
49             required to use Linux's C socket family. It is suggested to use
50             the high-level object interface to this instead; see L.
51              
52             =cut
53              
54             =head1 CONSTANTS
55              
56             The following constants are exported
57              
58             =over 8
59              
60             =item PF_NETLINK
61              
62             The packet family (for C calls)
63              
64             =item AF_NETLINK
65              
66             The address family
67              
68             =back
69              
70             =cut
71              
72             =head1 ADDRESS FUNCTIONS
73              
74             The following pair of functions operate on C address structures.
75             The meainings of the parameters are:
76              
77             =over 8
78              
79             =item pid
80              
81             The unique endpoint number for this netlink socket. If given as 0 to the
82             C syscall, the kernel will allocate an endpoint number of the
83             process's PID.
84              
85             =item groups
86              
87             A 32-bit bitmask of the multicast groups to join.
88              
89             =back
90              
91             =head2 $addr = pack_sockaddr_nl( $pid, $groups )
92              
93             Returns a C structure with the fields packed into it.
94              
95             =head2 ( $pid, $groups ) = unpack_sockaddr_nl( $addr )
96              
97             Takes a C structure and returns the unpacked fields from it.
98              
99             =cut
100              
101             =head1 STRUCTURE FUNCTIONS
102              
103             The following function pairs operate on structure types used by netlink
104              
105             =head2 $buffer = pack_nlmsghdr( $type, $flags, $seq, $pid, $body )
106              
107             =head2 ( $type, $flags, $seq, $pid, $body, $morebuffer ) = unpack_nlmsghdr( $buffer )
108              
109             Pack or unpack a C and its payload body.
110              
111             Because a single netlink message can contain more than payload body, the
112             C function will return the remaining buffer after unpacking
113             the first message, in case there are others. If there are no more, the
114             C<$morebuffer> list element will not be returned.
115              
116             while( defined $buffer ) {
117             ( my ( $type, $flags, $seq, $pid, $body ), $buffer ) = unpack_nlmsghdr( $buffer );
118             ...
119             }
120              
121             There is no similar functionallity for C; simply concatenate
122             multiple results together to send more than one message.
123              
124             =head2 $buffer = pack_nlmsgerr( $error, $msg )
125              
126             =head2 ( $error, $msg ) = unpack_nlmsgerr( $buffer )
127              
128             Pack or unpack a C. The kernel expects or reports negative
129             integers in its structures; these functions take or return normal positive
130             error values suitable for use with C<$!>.
131              
132             =head2 $buffer = pack_nlattrs( %attrs )
133              
134             =head2 %attrs = unpack_nlattrs( $buffer )
135              
136             Pack or unpack a list of netlink attributes.
137              
138             These functions take or return even-sized lists of C<$type, $value> pairs.
139             The type will be the number in the netlink attribute message, and the value
140             will be a plain packed string buffer. It is the caller's responsibilty to
141             further pack/unpack this buffer as appropriate for the specific type.
142              
143             Because these functions take/return even-sized lists, they may be passed or
144             returned into hashes.
145              
146             =cut
147              
148             =head1 SEE ALSO
149              
150             =over 4
151              
152             =item *
153              
154             C - netlink - Communication between kernel and userspace (AF_NETLINK)
155              
156             =item *
157              
158             L - Object interface to C domain sockets
159              
160             =back
161              
162             =head1 AUTHOR
163              
164             Paul Evans
165              
166             =cut
167              
168             0x55AA;