README.md
1# Longest Prefix Match (LPM) library
2
3[](https://travis-ci.org/rmind/liblpm)
4
5Longest Prefix Match (LPM) library supporting IPv4 and IPv6.
6The implementation is written in C99 and is distributed under the
72-clause BSD license.
8
9Additionally, bindings are available for **Lua** and **Java**.
10Specifications to build RPM and DEB packages are also provided.
11
12## API
13
14* `lpm_t *lpm_create(void)`
15 * Construct a new LPM object.
16
17* `void lpm_destroy(lpm_t *lpm)`
18 * Destroy the LPM object and any entries in it.
19
20* `void lpm_clear(lpm_t *lpm, lpm_dtor_t *dtor, void *arg)`
21 * Remove all entries in the LPM object. It calls the passed destructor
22 function, if it is not `NULL`, as it traverses the entries. The destructor
23 function prototype:
24 * `typedef void (*lpm_dtor_t)(void *arg, const void *key, size_t len, void *val);`
25
26* `int lpm_insert(lpm_t *lpm, const void *addr, size_t len, unsigned preflen, void *val)`
27 * Insert the network address of a given length and prefix length into
28 the LPM object and associate the entry with specified pointer value.
29 The address must be in the network byte order. Returns 0 on success
30 or -1 on failure.
31
32* `int lpm_remove(lpm_t *lpm, const void *addr, size_t len, unsigned preflen)`
33 * Remove the network address of a given length and prefix length from
34 the LPM object. Returns 0 on success or -1 on failure.
35
36* `void *lpm_lookup_prefix(lpm_t *lpm, const void *addr, size_t len, unsigned preflen)`
37 * Retrieve the pointer associated with a specific prefix.
38 Returns the said pointer, or `NULL` on failure.
39
40* `void *lpm_lookup(lpm_t *lpm, const void *addr, size_t len)`
41 * Lookup the given address performing the longest prefix match.
42 Returns the associated pointer value on success or `NULL` on failure.
43
44* `int lpm_strtobin(const char *cidr, void *addr, size_t *len, unsigned *preflen)`
45 * Convert a string in CIDR notation to a binary address, to be stored in
46 the `addr` buffer and its length in `len`, as well as the prefix length (if
47 not specified, then the maximum length of the address family will be set).
48 The address will be stored in the network byte order. Its buffer must
49 provide at least 4 or 16 bytes (depending on the address family). Returns
50 zero on success and -1 on failure.
51
52## Examples
53
54### Lua
55
56```lua
57local lpm = require("lpm")
58
59local acl = lpm.new()
60local some_info = { val = "test" }
61
62local addr, preflen = lpm.tobin("10.0.0.0/24")
63if not acl:insert(addr, preflen, some_info) then
64 print("acl:insert() failed")
65 return -1
66end
67
68local ret = acl:lookup(lpm.tobin("10.0.0.100"))
69print(ret.val)
70```
71
72### Java
73
74See [README](src/jni) how to build the JAR and the
75[test case](src/jni/org/netbsd/liblpm/LPMTest.java) as example
76how to use the Java API
77
78## Packages
79
80Just build the package, install it and link the library using the
81`-llpm` flag.
82* RPM (tested on RHEL/CentOS 7): `cd pkg && make rpm`
83* DEB (tested on Debian 9): `cd pkg && make deb`
84
){kind=link}