Debian Codegraph @

python/doc/core.rst

raw
1 *******************
2 Netlink Core Module
3 *******************
4
5 .. py:module:: netlink.core
6
7 Examples::
8
9 import netlink.core as netlink
10
11 ===============
12 Object
13 ===============
14
15 .. py:class:: Object
16
17 Base class for all classes representing a cacheable object
18
19 Example::
20 obj = netlink.Object("route/link", "link")
21
22 .. py:method:: clone
23
24 Clone the object and return a duplicate (used for COW)
25
26 .. py:method:: dump([params=None])
27
28 Call the libnl internal dump mechanism to dump the object
29 according to the parameters specified.
30
31 .. py:method:: apply(attr, val)
32
33 Applies a attribute=value pair and modifies the object accordingly.
34 Example::
35 obj.apply("mtu", 1200) # Sets attribute mtu to 1200 (link obj)
36
37 :raises: KeyError if attribute is unknown
38 :raises: ImmutableError if attribute is not mutable
39
40 .. py:attribute:: mark
41
42 True if the object is marked, otherwise False.
43
44 .. py:attribute:: shared
45
46 True if the object is used by multiple parties, otherwise False.
47
48 .. py:attribute:: refcnt
49
50 Number of users sharing a reference to the object
51 :rtype: int
52
53 .. py:attribute:: attrs
54
55 List of attributes
56
57 :rtype: list of strings
58
59 ===============
60 Cache
61 ===============
62
63 .. py:class:: Cache
64
65 Base class for all cache implementations.
66
67 A cache is a collection of cacheable objects which is typically used
68 by netlink protocols which handle any kind of object, e.g. network
69 links, network addresses, neighbours, ...
70
71 .. py:method:: subset(filter)
72
73 Returns a new cache containing the subset which matches the
74 provided filter.
75
76 :raises: ValueError if no filter is specified
77 :rtype: :py:class:`Cache`
78
79 .. py:method:: dump([params=None, filter=None])
80
81 Calls the libnl internal dump mechanism to dump the cache according
82 to the parameters and filter specified.
83
84 .. py:method:: clear()
85
86 Remove and possibly destroy all objects in the cache
87
88 .. py:method:: refill([socket=None]) -> :py:class:`Cache`
89
90 Clears and refills the cache with the content which is provided by
91 the kernel, e.g. for a link cache this would mean refilling the
92 cache with all configured network links.
93
94 .. py:method:: provide()
95
96 Caches which have been "provided" are made available to other users
97 (of the same application context) which "require" it. F.e. a link
98 cache is generally provided to allow others to translate interface
99 indexes to link names
100
101
102 .. py:method:: unprovide()
103
104 No longer make the cache available to others. If the cache has been
105 handed out already, that reference will still be valid.
106
107 ===============
108 AbstractAddress
109 ===============
110
111 .. py:class:: AbstractAddress
112
113 Abstract representation of an address. This class is not to be mistaken
114 with :py:class:`route.Address` which represents a configured network
115 address. This class represents the actual address in a family independent
116 way::
117
118 addr = netlink.AbstractAddress('127.0.0.1/8')
119 print addr # => '127.0.0.1/8'
120 print addr.prefixlen # => '8'
121 print addr.family # => 'inet'
122 print len(addr) # => '4' (32bit ipv4 address)
123
124 a = netlink.AbstractAddress('10.0.0.1/24')
125 b = netlink.AbstractAddress('10.0.0.2/24')
126 print a == b # => False
127
128 .. py:attribute:: prefixlen
129
130 Length of prefix in number of bits.
131
132 :rtype: int
133
134 .. py:attribute:: family
135
136 The family type of the address. Setting the address family can be
137 done with a string or a :py:class:`AddressFamily` object.
138
139 :rtype: :py:class:`AddressFamily`
140
141 .. py:attribute:: shared
142
143 True if address is in use by multiple callers, otherwise False
144
145 :rtype: bool
146
147 ===============
148 AddressFamily
149 ===============
150
151 .. py:class:: AddressFamily
152
153 Address family representation::
154
155 af = netlink.AddressFamily('inet6')
156 # raises:
157 # - ValueError if family name is not known
158 # - TypeError if invalid type is specified for family
159
160 print af # => 'inet6' (string representation)
161 print int(af) # => 10 (numeric representation)
162 print repr(af) # => AddressFamily('inet6')
163
164 ===============
165 Exceptions
166 ===============
167
168 .. py:exception:: NetlinkError
169
170 Generic exception raised by netlink modules.
171
172 .. py:exception:: KernelError
173
174 Raised if an error occured while communicating with the kernel. Contains
175 the error code returning which is automatically included in the error
176 message.
177
178 .. py:exception:: ImmutableError
179
180 Raised if an attribute is modified which is marked immutable.
181
182 ===============
183 Socket
184 ===============
185
186 .. py:class:: Socket
187
188 Netlink socket.
189
190 Note: It is not required to manually create and connect netlink sockets
191 when using caches. The caches will automatically lookup or create a
192 socket as needed.
193
194 .. py:attribute:: local_port
195
196 Local port (address) of netlink socket
197
198 .. py:attribute:: peer_port
199
200 Peer port (remote address) of netlink socket. If set, all messages
201 will be sent to that peer.
202
203 .. py:method:: connect(proto)
204
205 Connect the netlink socket using the specified netlink protocol::
206 sock.connect(netlink.NETLINK_ROUTE)
207
208 .. py:method:: disconnect()
209
210 Disconnect the socket
211
212 .. py:method:: set_bufsize(rx, tx)
213
214 Sets the size of the socket buffer
215