This page uses CSS for all styling, which your browser doesn't support. This page will look pretty bland, but you'll still be able to read every word.

libcidr

Jump to download

Summary

libcidr is a library that provides a number of functions to input, output, manipulate, compare, multilate, and otherwise play with, IP addresses and netblocks.

It supports both IPv4 and IPv6, and provides sufficiently diverse functions to be useful for everything from log processes to network client and server programs. It parses addresses in a wide variety of common formats, even including compressed IPv4 addresses and PTR record .in-addr.arpa, ip6.arpa, and .ip6.int styles. It provides a plethora of options for formatting them on the output as well. It will stuff them into and lever them out of the common structures used by the socket and DNS lookup functions. It'll compare them to each other in various ways, and give you some useful statistics about the addresses and the netblocks in which they reside. It'll generally make it easy for you to slice, dice, shred, toss, and julienne to your heart's content.

The build is pretty self-contained. It contains Makefiles for both Berkeley and GNU makes. Documentation is provided in the form of a manpage which provides a quick summary of the functions, and an exhaustive reference manual in a wide variety of formats, all generated based on my codelibrary SGML DTD, like I do on the libpostal project. The manual is also available online.

There are a few places where it connects up to IPv6 OS capabilities, primarily the struct in6_addr. Pretty much any modern POSIX system will have that around. It also requires the POSIX/C99 uintX_t types, which most systems should have. If your system lacks either of these, it's possible to just disable those bits or work around it reasonably easily if you're familiar with C. If not, drop me an email and I can try and give you a hand.

Other than that, it's pretty straightforward. It shouldn't have any other external dependancies.

libcidr is developed using the Bazaar (bzr) version control system. I've used CVS for many years for just about everything, including this webpage. CVS has a long and well-known list of faults and failings, though. Slowly, I'm replacing it with bzr for my stuff. Give it a try sometime; you might like it.

Documentation

I've put a copy of the reference manual for the current version (1.1) up in a couple formats. These files (and several other formats) are also in the release tarball, and are installed on your system by the "make install" process.

Examples

Several example and test programs are also included, which are good reference if you want to use the library. The test programs are really intended for development testing and verification, but can still be quite useful to show how the functions work. The example programs are more intended to show more "realistic" applications of the library functions. The two example programs are:

acl

which is a simple implementation of IP-based access control lists using libcidr's provided functions. It reads a simple ACL file containing allow/deny rules, evaluates the rulesets first match, and accepts or denies incoming telnet connections based on source IP. If you're interested in adding IP-based behavior modifications to your application (which was one of the primary inspirations for me to write this library myself), take a look at this example; it'll give you a good idea how easy it is to pull off.

cidrcalc

is a program similar to ipcalc in that it takes in a CIDR block, and gives you a quick set of stats about it; number of hosts in the given subnet, network and broadcast addresses, netmask in prefix and netmask form, Cisco-style wildcard mask, and optionally binary expansion and super/subnet info. Unlike ipcalc, though, it supports IPv6. Useful thing to have around when you're planning your subnetting scheme.

Note that cidrcalc is also installed by default in $DESTDIR/bin (usually /usr/local/bin) when you install the library. It's a handy tool, so I figured it might as well be available.

Installation

See the README file in the tarball for details of installation.

Downloads

libcidr 1.1 is the current version. This adds flexibility in the address parsing over 1.0. Notably, it supports the compressed IPv4 forms, as well as properly interpretting hex and octal in v4 addresses, if you're crazy enough to use either one. It fixes a lot of little bugs in the address parsing, and adds the ability to run automated regression tests against the address parsing routines (which are the big source of bugs, because they're very convoluted). It also adds a number of scattered little robustness fixups, and patches up a few warts in the build process.

Old versions