Your browser doesn't seem to support CSS, which this page uses for all styling. Don't be surprised if it looks kinda boring.

[Jump to nav]

libcidr

Quick Links

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.

Documentation

I've put a copy of the reference manual for the current version (1.2) (covers all 1.2.x versions) 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 $PREFIX/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.2.3.tar.xz is the current version. This has additional build system improvements, and some clarification in the docs.

Dev

libcidr is developed using the Bazaar (bzr) version control system. Occasionally, there's something useful in the development VCS branch between releases, so if you really want to dig into the history, I keep a sometimes-up-to-date mirror on Launchpad.

Old versions

  • libcidr 1.2.2 made more build changes for packagers' convenience.
  • libcidr 1.2.1 did some reorganizations of the build process, mostly at the request of and for the benefit of people making packages for various OSen.
  • libcidr 1.2 (bz2 version) fixed up some minor bugs in cidr_addr_host{min,max}() and cleaned up a lot of warnings in newer compilers (especially clang). It also has a few minor tweaks to the docs, and some changes in the build process to make things easier for packagers.
  • libcidr 1.1 improved the address parsing and added some semi-automated testing.
  • libcidr 1.0 was the first release.