libcidr is a library to make it easier to handle IP addresses and blocks, and manipulate them in various ways.
The core of the library is a pair of functions that take a human readable string and turn it into our internal representation of a CIDR address block (cidr_from_str() ), and one to take that internal representation and turn it into a human-readable string (cidr_to_str() ). There are a large number of options for how to format that string, as well.
Additionally, there are functions to compare different CIDR blocks, to determine if they're equal, or if one is contained within the other. This functionality can be useful for writing access-control code, or client-dependant configuration, or similar things. There are functions to manipulate address blocks and determine attributes of them, like network/broadcast addresses, the range of host addresses, the number of available host addresses, etc. There are functions to split a CIDR block into the two smaller blocks it contains, or to derive the parent block that it is itself contained within. And there are functions to translate to and from in_addr-type structures, which the operating system commonly uses to represent addresses for handle socket connections and so forth.
In short, just about anything you might do in a program with IP addressing, whether referring to individual hosts, or to any sized subnets, libcidr is designed to simplify handling. It's not a DNS library, nor is it a socket abstraction layer. It's just a set of functions for manipulating raw IP addresses in various ways.
The functions generally follow standard C conventions. They tend to return 0 or a pointer when acting properly, and -1 or NULL when something went wrong (unless the function usage suggests other returns, of course, as in cidr_get_pflen() ). They set errno when returning an error; the error codes each function can return are documented with the function.
libcidr doesn't use any threading itself. It should, however, be safe to use in any threaded program if used sensibly. Only a very few functions use static strings, and those that do (cidr_version() and cidr_numaddr() and its related functions being the only ones I can think of) tend to be constant strings as well, so they wouldn't be changing. Of course, you don't want to cidr_free() a CIDR in one thread while you're still using it in another, but if you do, it's not libcidr's fault.
For the current version or any extra information, see the libcidr project homepage, at <http://www.over-yonder.net/~fullermd/projects/libcidr>.
This reference manual is build using the codelibrary SGML DTD, which is specifically designed for documenting libraries. See the codelibrary homepage at <http://www.over-yonder.net/~fullermd/projects/sgml/codelibrary> for more details on it.
This datatype is intended for internal use only
Note:
Use the cidr_free() function to free the memory associated with this datatype, and the cidr_alloc() function to allocate and initialize the structure.
Generate a CIDR structure describing the broadcast address of the passed-in netblock.
Note that using this with an IPv6 netblock is technically asking for something that doesn't exist, since IPv6 doesn't have subnet broadcast addresses. This function will still return the all-1's address though, on the assumption that if you're asking the question, it's the answer you want.
An additional somewhat specialized case is that of an IPv4 /31 or IPv6 /127. Depending on your interpretation and usage, this is either a useless subnet since it only contains network and broadcast and no hosts, or a subnet that holds 2 hosts with neither network or broadcast address (commonly used for point-to-point links). As a result, cidr_addr_broadcast() and cidr_addr_network() will give answers as if it were a host-less subnet, while cidr_addr_hostmax() and cidr_addr_hostmin() will answer as though it were a 2-host subnet. It can be seen as a little strange for cidr_addr_broadcast() and cidr_addr_hostmax() to give the same answer, but as above, libcidr assumes that if you ask the question, you want the answer that makes sense in that context.
Similar caveats apply to calling these on a v4 /32 or v6 /128. Ask a silly question, get a silly answer :)
The returned structure should be cleaned up using cidr_free() .
CIDR *
Returns a pointer to a CIDR structure describing the broadcast address on success. Returns NULL on failure.
Note:
cidr_addr_broadcast() can also fail and set errno for any of the reasons listed for cidr_alloc() .
Generate a CIDR structure describing the highest-numbered address available for a host IP in the given netblock.
See the discussion under cidr_addr_broadcast() concerning near- amd maximal-prefix-length blocks for edge case details.
The returned structure should be cleaned up using cidr_free() .
CIDR *
Returns a pointer to a CIDR structure describing the max host address on success. Returns NULL on failure.
Note:
cidr_addr_hostmax() can fail and set errno for any of the reasons listed for cidr_addr_broadcast() .
Generate a CIDR structure describing the lowest-numbered address available for a host IP in the given netblock.
See the discussion under cidr_addr_broadcast() concerning near- amd maximal-prefix-length blocks for edge case details.
The returned structure should be cleaned up using cidr_free() .
CIDR *
Returns a pointer to a CIDR structure describing the min host address on success. Returns NULL on failure.
Note:
cidr_addr_hostmin() can fail and set errno for any of the reasons listed for cidr_addr_network() .
Generate a CIDR structure describing the network address of the passed-in netblock.
See the discussion under cidr_addr_broadcast() concerning near- amd maximal-prefix-length blocks for edge case details.
The returned structure should be cleaned up using cidr_free() .
CIDR *
Returns a pointer to a CIDR structure describing the network address on success. Returns NULL on failure.
Note:
cidr_addr_network() can also fail and set errno for any of the reasons listed for cidr_alloc() .
Allocate memory for a CIDR structure and initialize the necessary pieces.
The returned structure should be cleaned up using cidr_free() .
Note that you should probably never need to call this function yourself; you'll generally get your CIDR structures as a return from a function like cidr_from_str() or cidr_from_inaddr() .
CIDR *
Returns a pointer to an initialized CIDR structure on success. Returns NULL on failure.
This function is passed two CIDR structures describing a pair of netblocks. It then determines if the latter is wholly contained within the former.
A common use-case of this will generally involve the second "block" actually being a host (/32 or /128) address, as when you're implementing ACL's. But that's really just a specific case of the second block being any other size; there's nothing special or magical about it. As far as libcidr is concerned, they're just two netblocks.
int
Returns 0 if little is wholly contained within big. Returns -1 if it's not, or if an error occured.
Allocate a CIDR , and fill it in with a duplicate of the information given.
The returned structure should be cleaned up using cidr_free() .
CIDR *
Returns a CIDR struct containing a copy of src. Returns NULL on failure.
Note:
cidr_dup() can fail and set errno for any of the reasons listed for cidr_alloc() .
Takes a populated struct in_addr, as you'd get from accept() or getaddrinfo() or similar functions. Parses it out and generates a CIDR structure based on it. Note that an in_addr only contains a host address, so the netmask is initialized to all-1's (/32).
CIDR *
Returns a pointer to a populated CIDR containing the address in the passed-in struct in_addr. The netmask is initialized to all-1's, and the protocol to IPv4. Use cidr_free() to free the structure when you're finished with it. Returns NULL on error.
Note:
cidr_from_inaddr() can also fail and set errno for any of the reasons listed for cidr_alloc() .
Takes a populated struct in6_addr, as you'd get from accept() or getaddrinfo() or similar functions. Parses it out and generates a CIDR structure based on it. Note that a in6_addr only contains a host address, so the netmask is initialized to all-1's (/128).
CIDR *
Returns a pointer to a populated CIDR containing the address in the passed-in struct in6_addr. The netmask is initialized to all-1's, and the protocol to IPv6 (though it may contain an IPv4-mapped address). Use cidr_free() to free the structure when you're finished with it. Returns NULL on error.
Note:
cidr_from_inaddr() can also fail and set errno for any of the reasons listed for cidr_alloc() .
Takes in a netblock description as a human-readable string, and creates a CIDR structure from it.
This is probably the most intricate function in the library. It accepts addresses in "address/mask" format. 'address' is an IP address in valid written form. For IPv4, it's 1 through 4 period-separated pieces, expressed in octal, hex, or decimal, with the last octet being treated as an 8, 16, 24, or 32-bit quantity depending on whether there are 4, 3, 2, or 1 pieces given (respectively). Of course, you're nuts for using that flexibility. For IPv6, it's nice and simple; 8 colon-separated double-octets, excepting that the last 4 octets can be expressed as a 4-piece dotted-decimal, like an IPv4 address (the full flexibility of the IPv4 parsing engine is not available, however; intentionally, though that may change if necessary). 'mask' can be either a prefix length (/0-/32 for IPv4, /0-/128 for IPv6), or a netmask written in the standard form for the address family.
IPv6 addresses can be specified in fully expanded form, or with ::-style contraction. IPv4-mapped IPv6 addresses (::ffff:a.b.c.d), will be treated as IPv6 addresses. The mask can be left off, in which case addresses are treated as host addresses (/32 or /128, depending on address family).
Also, cidr_from_str() will parse DNS PTR-record-style address formats. That is, representations like "4.3.2.1.in-addr.arpa" for IPv4, and an extremely long and annoying form ending in .ip6.arpa for IPv6. cidr_from_str() also understands the deprecated RFC1886 form of IPv6 PTR records, which ends in .ip6.int, though cidr_to_str() will only generate the current RFC3152-style .ip6.arpa version. Note also that while cidr_to_str() treats all addresses as host addresses when building the PTR string (ignoring the netmask), cidr_from_str() will fill in the netmask bits as appropriate for the string given; any octets (or half-octets, in the IPv6 form) that are left off the beginning will have their netmask bits set to 0.
It's not the intention of the author that this function necessarily be able to decipher any possible address format. However, the capabilities given should parse any rational address specification, and many irrational ones (like hex/oct and collapsed v4 addresses). The intention is rather to support the ways the addresses and netmasks are commonly written and read, so that a human-readable form can quickly be transformed into a format that libcidr can then use in its various ways, whether through comparing addresses with functions like cidr_contains() , or generating references and stats about a netblock with functions like cidr_addr_broadcast() and cidr_numhost() , or simply spitting it out in different human-readable forms with cidr_to_str() .
CIDR *
Returns a pointer to a populated CIDR describing (hopefully) the block you talked about in the string. Use cidr_free() to free the structure when you're finished with it. Returns NULL on error.
Note:
cidr_from_str() can also fail and set errno for any of the reasons listed for cidr_alloc() or cidr_get_pflen() .
Return the address bits which compose the address. This should be used in preference to simply referencing inside the CIDR manually in external code, since the structure might change on you.
Generally, if you think you need to call this, you should probably rethink what you're doing. Most of the time, one of the formatted outputs from cidr_to_str() or one of the manipulation functions like cidr_addr_hostmin() is what you want. Still, there are times when you're interesting in manipulating the address by yourself as a bunch of binary bits (the cidrcalc example program does this), so this function should be used instead of groping around in the structure manually.
uint8_t *
Returns a pointer to an 16-element array of uint8_t's representing the address. This array must be free() 'd when you're through with it. Returns NULL on error.
Return the netmask bits which of the given netblock. This should be used in preference to simply referencing inside the CIDR manually in external code, since the structure might change on you.
See further notes about the desirability of using this function above in the notes for cidr_get_addr() .
uint8_t *
Returns a pointer to an 16-element array of uint8_t's representing the netmask. This array must be free() 'd when you're through with it. Returns NULL on error.
Poke around the netmask of the passed-in CIDR structure and determine how many bits there are in the netmask, as appropriate to the address family.
int
Returns the number of network bits in the netmask (0-32 for IPv4, 0-128 for IPv6). Returns -1 on error.
Returns the protocol family of an address using one of the defined constants. The current choices are CIDR_IPV4 and CIDR_IPV6.
int
Returns the address family of the given netblock.
An IPv6 address may be in the network range reserved for IPv4-mapped addresses. This function will tell you whether it is or not. Note that an IPv4 CIDR is NOT considered an IPv4-mapped address, and so will return failure.
int
Returns 0 if the address is an IPv4-mapped IPv6 address. Returns -1 otherwise.
Take in a netblock, and derive the two netblocks which it divides up into. Return them in an array.
CIDR **
Returns a 2-element array of CIDR structs, containing the two subnets of addr. Each of the elements should be cleaned up with cidr_free() , and the array itself then cleaned up with free() . Returns NULL on failure.
Note:
cidr_net_subnets() can also fail and set errno for any of the reasons listed for cidr_addr_network() or cidr_dup() .
Take in a netblock, and derive the parent netblock in which it fits.
CIDR *
Returns a CIDR struct defining the parent network of addr. Clean this up with cidr_free() when you're finished with it. Returns NULL on failure.
Note:
cidr_net_supernet() can also fail and set errno for any of the reasons listed for cidr_dup() .
Determine the total number of addresses in a netblock (including the network and broadcast addresses).
This function returns a pointer to a pre-formatted string because we're potentially returning a value up to 2**128. I don't feel like trying to portably do 128-bit arithmetic. Do you?
const char *
Returns a pointer to a string containing the number of addresses in the netblock. Note that this is a static string; it should not be overwritten, and doesn't need to be free() 'd. Make a copy if you want to manipulate it. Returns NULL on error.
Note:
cidr_numaddr() can also also fail and set errno for any of the reasons listed for cidr_numaddr_pflen() .
Determine the total number of addresses in a netblock with the given prefix length (including the network and broadcast addresses).
Note that this takes an IPv6 prefix length; that is, 0-128. If you're interested in an IPv4 address with a given prefix length, add 96 to it when you call this function.
See the note in cidr_numaddr() for why we're returning a string and not a number.
const char *
Returns a pointer to a string containing the number of addresses in the netblock. Note that this is a static string; it should not be overwritten, and doesn't need to be free() 'd. Make a copy if you want to manipulate it. Returns NULL on error.
Determine the total number of host addresses in a netblock (excluding the network and broadcast addresses).
See the note in cidr_numaddr() for why we're returning a string and not a number.
const char *
Returns a pointer to a string containing the number of host addresses in the netblock. Note that this is a static string; it should not be overwritten, and doesn't need to be free() 'd. Make a copy if you want to manipulate it. Returns NULL on error.
Note:
cidr_numhost() can also also fail and set errno for any of the reasons listed for cidr_numhost_pflen() .
Determine the total number of host addresses in a netblock with the given prefix length (excluding the network and broadcast addresses).
Note that this takes an IPv6 prefix length; that is, 0-128. If you're interested in an IPv4 address with a given prefix length, add 96 to it when you call this function.
See the note in cidr_numaddr() for why we're returning a string and not a number.
const char *
Returns a pointer to a string containing the number of host addresses in the netblock. Note that this is a static string; it should not be overwritten, and doesn't need to be free() 'd. Make a copy if you want to manipulate it. Returns NULL on error.
Takes in a CIDR and creates a struct in_addr from it. This struct can then be used in connect() or similar network-related functions. If the users passes in a struct in_addr, it will be filled in. Otherwise, one will be allocated and returned.
struct in_addr *
Returns a pointer to the filled-in struct in_addr. If the user passed one in, this will just point to the same place and can profitably be ignored. If the user passed in NULL, this will point to the struct in_addr we allocated, which should be free() 'd by the user when they're finished with it. Returns NULL on error.
Takes in a CIDR and creates a struct in6_addr from it. This struct can then be used in connect() or similar network-related functions. If the users passes in a struct in6_addr, it will be filled in. Otherwise, one will be allocated and returned.
struct in6_addr *
Returns a pointer to the filled-in struct in6_addr. If the user passed one in, this will just point to the same place and can profitably be ignored. If the user passed in NULL, this will point to the struct in6_addr we allocated, which should be free() 'd by the user when they're finished with it. Returns NULL on error.
Takes in a CIDR structure, and generates up a human-readable string describing the netblock. This function has a lot of flexibility, depending on the flags passed to it. The default output is "address/pflen" form, with the address in a reasonably compact form, and the prefix length given numerically. Flags alter the output in various ways, and are set as bitmasks, so they can be combined however you wish. They can be used in any combination that makes sense, and a large number of combinations that don't.
The current flags are:
CIDR_NOFLAGS: A stand-in for when you just want the default
output
CIDR_NOCOMPACT: Don't do ::-style IPv6 compaction
CIDR_VERBOSE: Show leading 0's in octets [v6 only]
CIDR_USEV6: Use IPv4-mapped address form for IPv4 addresses
(::ffff:a.b.c.d)
CIDR_USEV4COMPAT: Use IPv4-compat form (::a.b.c.d) instead of
IPv4-mapped form (only meaningful in combination with
CIDR_USEV6)
CIDR_NETMASK: Return a netmask in standard form after the
slash, instead of the prefix length. Note that the form of the
netmask can thus be altered by the various flags that alter
how the address is displayed.
CIDR_ONLYADDR: Show only the address, without the
prefix/netmask
CIDR_ONLYPFLEN: Show only the prefix length (or netmask, when
combined with CIDR_NETMASK), without the address.
CIDR_WILDCARD: Show a Cisco-style wildcard mask instead of the
netmask (only meaningful in combination with CIDR_NETMASK)
CIDR_FORCEV6: Forces treating the CIDR as an IPv6 address, no matter what it
really is. This doesn't do any conversion or translation; just
treats the raw data as if it were IPv6.
CIDR_FORCEV4: Forces treating the CIDR as an IPv4 address, no matter what it
really is. This doesn't do any conversion or translation; just
treats the raw data as if it were IPv4.
CIDR_REVERSE: Generates a .in-addr.arpa or .ip6.arpa-style PTR
record name for the given block. Note that this always treats
it solely as an address; the netmask is ignored. See some
notes in cidr_from_str() for
details of the asymmetric treatment of this form of address
representation relating to the netmask.
Many combinations can give somewhat surprising results, but they should allow any of a host of manipulations to output just the data you might be interested in. The "mkstr" test program in the source tree is extremely useful for manual testing of the various flags to see visually what they do, and is a lot quicker than trying to code them all to test it out. Use it to your advantage.
char *
Returns a pointer to a string containing the representation of the network. Be sure to free() it when you're finished.
Note:
cidr_to_str() can also fail and set errno for any of the reasons listed for cidr_alloc() or cidr_get_pflen() .
Returns a static string describing the library release version.
const char *
Returns a pointer to a static string describing the library version number. It shouldn't be overwritten or free() 'd.