Summary:
    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.    

Contents
Data structures:
CIDR (Internal)
Functions:
cidr_addr_broadcast()
cidr_addr_hostmax()
cidr_addr_hostmin()
cidr_addr_network()
cidr_alloc()
cidr_contains()
cidr_dup()
cidr_equals()
cidr_free()
cidr_from_inaddr()
cidr_from_in6addr()
cidr_from_str()
cidr_get_addr()
cidr_get_mask()
cidr_get_pflen()
cidr_get_proto()
cidr_is_v4mapped()
cidr_net_subnets()
cidr_net_supernet()
cidr_numaddr()
cidr_numaddr_pflen()
cidr_numhost()
cidr_numhost_pflen()
cidr_to_inaddr()
cidr_to_in6addr()
cidr_to_str()
cidr_version()

  Data structures:
- CIDR:    A single CIDR-format IP block
*** This datatype is 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.     
Members:
- int version:         The structure version.      This is reserved for future use, and put in to hold its place at the      start of the array.     
- uint8_t addr[16]:         The 16 octets that make up an IP address.      For v6 addresses, all are used.      For v4 addresses, only the last 4 are really used.      The prior 2 octets are filled in with all-ones, so that the internal      representation matches the v4-compat IPv6 addressing block.      This is useful when, for instance, using      cidr_to_in6addr(), in that it gives you the expected      result.     
- uint8_t mask[16]:         The 16 octets that make up an IP netmask.      For v4 addresses, only the last 4 are really used; the rest are      intialized to all-bits-one however, which is correct in spirit.     
- int proto:         The protocol the address described is.      Currently possible values are CIDR_IPV4 and CIDR_IPV6.      I think that's pretty self-explanatory.     

  Functions:
- cidr_addr_broadcast():       Find the broadcast address    
Summary:
     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().     
Arguments:
- const CIDR * addr:          A CIDR structure describing an arbitrary       netblock.      
Return value:
CIDR *
      Returns a pointer to a CIDR structure       describing the broadcast address on success.       Returns NULL on failure.      
Error codes:
- [EFAULT]
Given NULL
Note:
      cidr_addr_broadcast() can also fail and set errno for       any of the reasons listed for cidr_alloc().      
- cidr_addr_hostmax():       Find the highest host address    
Summary:
     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().     
Arguments:
- const CIDR * addr:          A CIDR structure describing an arbitrary       netblock.      
Return value:
CIDR *
      Returns a pointer to a CIDR structure       describing the max host address on success.       Returns NULL on failure.      
Error codes:
Note:
      cidr_addr_hostmax() can fail and set errno for any       of the reasons listed for cidr_addr_broadcast().      
- cidr_addr_hostmin():       Find the lowest host address    
Summary:
     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().     
Arguments:
- const CIDR * addr:          A CIDR structure describing an arbitrary       netblock.      
Return value:
CIDR *
      Returns a pointer to a CIDR structure       describing the min host address on success.       Returns NULL on failure.      
Error codes:
Note:
      cidr_addr_hostmin() can fail and set errno for any       of the reasons listed for cidr_addr_network().      
- cidr_addr_network():       Find the network address    
Summary:
     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().     
Arguments:
- const CIDR * addr:          A CIDR structure describing an arbitrary       netblock.      
Return value:
CIDR *
      Returns a pointer to a CIDR structure       describing the network address on success.       Returns NULL on failure.      
Error codes:
- [EFAULT]
Given NULL
Note:
      cidr_addr_network() can also fail and set errno for       any of the reasons listed for cidr_alloc().      
- cidr_alloc():       Create a CIDR    
Summary:
     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().     
Arguments:
None.
Return value:
CIDR *
      Returns a pointer to an initialized CIDR       structure on success.       Returns NULL on failure.      
Error codes:
- [ENOMEM]
malloc() failed
- cidr_contains():       Compare netblocks    
Summary:
     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.     
Arguments:
- const CIDR * big:          The netblock which may (or may not) contain the second arg.      
- const CIDR * little:          The netblock which may (or may not) be contained within the first       arg.      
Return value:
int
      Returns 0 if little is wholly contained within big.       Returns -1 if it's not, or if an error occured.      
Error codes:
- [0]
No error (little not in big)
- [EFAULT]
Passed NULL
- [EINVAL]
Invalid argument
- [ENOENT]
Internal error (shouldn't happen)
- [EPROTO]
Protocols don't match
- cidr_dup():       Duplicate a netblock    
Summary:
     Allocate a CIDR, and fill it in with a      duplicate of the information given.     
     The returned structure should be cleaned up using      cidr_free().     
Arguments:
- const CIDR * src:          A CIDR structure to be copied.      
Return value:
CIDR *
      Returns a CIDR struct containing a copy of       src.       Returns NULL on failure.      
Error codes:
Note:
      cidr_dup() can fail and set errno for any of the       reasons listed for cidr_alloc().      
- cidr_equals():       Compare two blocks for equality    
Summary:
     This function is passed two CIDR structures      describing a pair of netblocks.      It checks to see if they happen to describe the same netblock.     
Arguments:
- const CIDR * one:          One netblock.      
- const CIDR * two:          Another netblock.      
Return value:
int
      Returns 0 if the two CIDR structs describe the       same netblock.       Returns -1 otherwise.      
- cidr_free():   Free a CIDR structure.
Summary:
     Takes a CIDR structure and      free()'s all its component parts.     
Arguments:
- CIDR * tofree:          A single CIDR structure which has outlived its       usefulness.      
Return value:
void
- cidr_from_inaddr():       Parse a struct in_addr    
Summary:
     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).     
Arguments:
- const struct in_addr * uaddr:          A populated struct in_addr, from whatever source obtained.      
Return value:
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.      
Error codes:
- [EFAULT]
Passed NULL
Note:
      cidr_from_inaddr() can also fail and set errno for       any of the reasons listed for cidr_alloc().      
- cidr_from_in6addr():       Parse a struct in6_addr    
Summary:
     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).     
Arguments:
- const struct in6_addr * uaddr:          A populated struct in6_addr, from whatever source obtained.      
Return value:
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.      
Error codes:
- [EFAULT]
Passed NULL
Note:
      cidr_from_inaddr() can also fail and set errno for       any of the reasons listed for cidr_alloc().      
- cidr_from_str():       Parse a human-readable string    
Summary:
     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().     
Arguments:
- const char * addr:          A string containing some human-readable IP block.      
Return value:
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.      
Error codes:
- [EFAULT]
Passed NULL
- [EINVAL]
Can't parse the input string
- [ENOENT]
Internal error (shouldn't happen)
Note:
      cidr_from_str() can also fail and set errno for any       of the reasons listed for       cidr_alloc() or       cidr_get_pflen().      
- cidr_get_addr():       Return address bits    
Summary:
     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.     
Arguments:
- const CIDR * addr:          An arbitrary netblock.      
Return value:
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.      
Error codes:
- [EFAULT]
Passed NULL
- [ENOMEM]
malloc() failed
- cidr_get_mask():       Return netmask bits    
Summary:
     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().     
Arguments:
- const CIDR * addr:          An arbitrary netblock.      
Return value:
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.      
Error codes:
- [EFAULT]
Passed NULL
- [ENOMEM]
malloc() failed
- cidr_get_pflen():       Network bits in the netmask    
Summary:
     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.     
Arguments:
- const CIDR * block:          An arbitrary netblock.      
Return value:
int
      Returns the number of network bits in the netmask (0-32 for IPv4,       0-128 for IPv6).       Returns -1 on error.      
Error codes:
- [EFAULT]
Passed NULL
- [EINVAL]
Invalid (non-contiguous) netmask
- [ENOENT]
Internal error (shouldn't happen)
- cidr_get_proto():       Find a netblock's protocol family    
Summary:
     Returns the protocol family of an address using one of the defined      constants.      The current choices are CIDR_IPV4 and CIDR_IPV6.     
Arguments:
- const CIDR * addr:          An arbitrary netblock.      
Return value:
int
      Returns the address family of the given netblock.      
Error codes:
- [EFAULT]
Passed NULL
- cidr_is_v4mapped():       Is address IPv4-mapped IPv6 address?    
Summary:
     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.     
Arguments:
- const CIDR * addr:          An arbitrary netblock.      
Return value:
int
      Returns 0 if the address is an IPv4-mapped IPv6 address.       Returns -1 otherwise.      
- cidr_net_subnets():       Divide a netblock    
Summary:
     Take in a netblock, and derive the two netblocks which it divides up      into.      Return them in an array.     
Arguments:
- const CIDR * addr:          The netblock to subdivide.      
Return value:
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.      
Error codes:
- [0]
No error (already a /32 or /128)
- [EFAULT]
Passed NULL argument
- [ENOMEM]
malloc() failed
Note:
      cidr_net_subnets() can also fail and set errno for       any of the reasons listed for       cidr_addr_network() or       cidr_dup().      
- cidr_net_supernet():       Undivide a netblock    
Summary:
     Take in a netblock, and derive the parent netblock in which it fits.     
Arguments:
- const CIDR * addr:          The netblock to find the parent of.      
Return value:
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.      
Error codes:
- [0]
No error (already a /0)
- [EFAULT]
Passed NULL argument
Note:
      cidr_net_supernet() can also fail and set errno for       any of the reasons listed for cidr_dup().      
- cidr_numaddr():       Addresses in a netblock    
Summary:
     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?     
Arguments:
- const CIDR * addr:          An arbitrary netblock.      
Return value:
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.      
Error codes:
- [EFAULT]
Passed NULL
Note:
      cidr_numaddr() can also also fail and set errno for       any of the reasons listed for cidr_numaddr_pflen().      
- cidr_numaddr_pflen():       Addresses in a prefix length    
Summary:
     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.     
Arguments:
- int pflen:          A prefix length (0-128).      
Return value:
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.      
Error codes:
- [EINVAL]
Invalid prefix length
- cidr_numhost():       Host addresses in a netblock    
Summary:
     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.     
Arguments:
- const CIDR * addr:          An arbitrary netblock.      
Return value:
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.      
Error codes:
- [EFAULT]
Passed NULL
Note:
      cidr_numhost() can also also fail and set errno for       any of the reasons listed for cidr_numhost_pflen().      
- cidr_numhost_pflen():       Host addresses in a prefix length    
Summary:
     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.     
Arguments:
- int pflen:          A prefix length (0-128).      
Return value:
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.      
Error codes:
- [EINVAL]
Invalid prefix length
- cidr_to_inaddr():       Create a struct in_addr    
Summary:
     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.     
Arguments:
- const CIDR * addr:          A CIDR structure describing the host to be       translated into a struct in_addr.       Note that the netmask is irrelevant and will be ignored.       cidr_to_inaddr() supports only IPv4 addresses, as the       underlying structure only does.      
- struct in_addr * uptr:          A pointer to a pre-allocated struct in_addr, or NULL.       If non-NULL, the pointed-at structure will be filled in.       If NULL, a new structure will be allocated, filled in, and       returned.      
Return value:
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.      
Error codes:
- [EFAULT]
Passed NULL
- [ENOMEM]
malloc() failed
- [EPROTOTYPE]
Bad protocol type (must be IPv4)
- cidr_to_in6addr():       Create a struct in6_addr    
Summary:
     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.     
Arguments:
- const CIDR * addr:          A CIDR structure describing the host to be       translated into a struct in6_addr.       Note that the netmask is irrelevant and will be ignored.       cidr_to_in6addr() supports both IPv4 and IPv6       addresses, as the underlying structure does as well.       IPv4 addresses are treated as v4-mapped IPv6 addresses.      
- struct in6_addr * uptr:          A pointer to a pre-allocated struct in6_addr, or NULL.       If non-NULL, the pointed-at structure will be filled in.       If NULL, a new structure will be allocated, filled in, and       returned.      
Return value:
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.      
Error codes:
- [EFAULT]
Passed NULL
- [ENOMEM]
malloc() failed
- [EPROTOTYPE]
Bad protocol type (must be IPv4 or IPv6)
- cidr_to_str():       Create a human-readable netblock description    
Summary:
     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.     
Arguments:
- const CIDR * block:          The CIDR structure to generate a string       form of.       The address family will be autodetected.      
- int flags:          A bitmask of the various possible flags the function accepts.      
Return value:
char *
      Returns a pointer to a string containing the representation of the       network.       Be sure to free() it when you're finished.      
Error codes:
- [EINVAL]
Invalid argument (bad block or flags)
- [ENOENT]
Internal error (shouldn't happen)
- [ENOMEM]
malloc() failed
Note:
      cidr_to_str() can also fail and set errno for       any of the reasons listed for       cidr_alloc() or       cidr_get_pflen().      
- cidr_version():       Library version    
Summary:
     Returns a static string describing the library release version.     
Arguments:
None.
Return value:
const char *
      Returns a pointer to a static string describing the library version       number.       It shouldn't be overwritten or free()'d.