1
2
3
4
5
6
7
|
{\rtf1\ansi\deff0
{\fonttbl{\f1\fnil\fcharset0 serif;}
{\f0\fnil\fcharset0 Times New Roman;}
}
{\colortbl;}{\stylesheet{\s0 Normal;}{\s1 Heading 1;}{\s2 Heading 2;}{\s3 Heading 3;}{\s4 Heading 4;}{\s5 Heading 5;}{\s6 Heading 6;}{\s7 Heading 7;}{\s8 Heading 8;}{\s9 Heading 9;}}
\deflang1024\notabind\facingp\hyphauto1\widowctrl
\sectd\plain\pgwsxn12240\pghsxn15840\marglsxn1440\margrsxn1440\margtsxn1440\margbsxn1440\headery0\footery0\pgndec{\headerl\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerl\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\headerr\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerr\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}\sect\sectd\plain\pgwsxn12240\pghsxn15840\marglsxn1440\margrsxn1440\margtsxn1440\margbsxn1440\headery0\footery0\pgndec{\headerl\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerl\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\headerr\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerr\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}\sect\sectd\plain\pgwsxn12240\pghsxn15840\marglsxn1440\margrsxn1440\margtsxn1440\margbsxn1440\headery0\footery0\pgndec{\headerl\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerl\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\headerr\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerr\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}\pard\sl240 \b\fs42\f1 Summary:\hyphpar0\par\pard\sb210\sl240 \b0\fs28 libcidr is a library to make it easier to handle IP addresses and blocks, and manipulate them in various ways. \hyphpar0\par\pard\sb105\sl240 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 (\b cidr_from_str()\b0 ), and one to take that internal representation and turn it into a human-readable string (\b cidr_to_str()\b0 ). There are a large number of options for how to format that string, as well. \hyphpar0\par\pard\sb105\sl240 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. \hyphpar0\par\pard\sb105\sl240 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. \hyphpar0\par\pard\sb105\sl240 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 \b cidr_get_pflen()\b0 ). They set errno when returning an error; the error codes each function can return are documented with the function. \hyphpar0\par\pard\sb105\sl240 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 (\b cidr_version()\b0 and \b cidr_numaddr()\b0 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 \b cidr_free()\b0 a \b CIDR\b0 in one thread while you're still using it in another, but if you do, it's not libcidr's fault. \hyphpar0\par\pard\sb105\sl240 For the current version or any extra information, see the libcidr project homepage, at <http://www.over-yonder.net/~fullermd/projects/libcidr>. \hyphpar0\par\pard\sb105\sl240 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. \hyphpar0\par\sect\sectd\plain\pgwsxn12240\pghsxn15840\marglsxn1440\margrsxn1440\margtsxn1440\margbsxn1440\headery0\footery0\pgndec{\headerl\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerl\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\headerr\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerr\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}\pard\li200\ri200\sl240 \b\fs42\f1 Contents\hyphpar0\par\pard\sb210\li300\ri300\sl240 \fs35 Data structures:\hyphpar0\par\pard\sb53\li400\ri400\sl240 \fs28 CIDR\b0\fs22 (Internal)\hyphpar0\par\pard\sb210\li300\ri300\sl240 \b\fs35 Functions:\hyphpar0\par\pard\sb53\li400\ri400\sl240 \fs28 cidr_addr_broadcast()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_addr_hostmax()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_addr_hostmin()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_addr_network()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_alloc()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_contains()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_dup()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_equals()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_free()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_from_inaddr()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_from_in6addr()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_from_str()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_get_addr()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_get_mask()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_get_pflen()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_get_proto()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_is_v4mapped()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_net_subnets()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_net_supernet()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_numaddr()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_numaddr_pflen()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_numhost()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_numhost_pflen()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_to_inaddr()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_to_in6addr()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_to_str()\hyphpar0\par\pard\sb53\li400\ri400\sl240 cidr_version()\hyphpar0\par\sect\sectd\plain\pgwsxn12240\pghsxn15840\marglsxn1440\margrsxn1440\margtsxn1440\margbsxn1440\headery0\footery0\pgndec{\headerl\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerl\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\headerr\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerr\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}\pard\sl240 \b\fs42\f1 Data structures:\hyphpar0\par\pard\sb420\sl240 \b0\fs35 - CIDR: \fs28 A single CIDR-format IP block\keepn\hyphpar0\par\pard\sb105\li400\ri400\sl240 \fs35 *** This datatype is for internal use only ***\keepn\hyphpar0\par\pard\li200\ri200\sl240 \fs28 Note:\keepn\hyphpar0\par\pard\sb210\li300\ri300\sl240 Use the \b cidr_free()\b0 function to free the memory associated with this datatype, and the \b cidr_alloc()\b0 function to allocate and initialize the structure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 Members:\hyphpar0\par\pard\sb210\li300\ri300\sl240 - int version: The structure version. This is reserved for future use, and put in to hold its place at the start of the array. \hyphpar0\par\pard\sb210\li300\ri300\sl240 - 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 \b cidr_to_in6addr()\b0 , in that it gives you the expected result. \hyphpar0\par\pard\sb210\li300\ri300\sl240 - 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. \hyphpar0\par\pard\sb210\li300\ri300\sl240 - int proto: The protocol the address described is. Currently possible values are CIDR_IPV4 and CIDR_IPV6. I think that's pretty self-explanatory. \hyphpar0\par\sect\sectd\plain\pgwsxn12240\pghsxn15840\marglsxn1440\margrsxn1440\margtsxn1440\margbsxn1440\headery0\footery0\pgndec{\headerl\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerl\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\headerr\pard\sl-240\sb0\sa1200\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}{\footerr\pard\sl-240\sb1200\sa0\plain\tqc\tx4680\tqr\tx9360 {}\tab {}\tab {}\par}\pard\sl240 \b\fs42\f1 Functions:\hyphpar0\par\pard\sb420\sl240 \b0\fs35 - cidr_addr_broadcast(): \fs28 Find the broadcast address \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Generate a \b CIDR\b0 structure describing the broadcast address of the passed-in netblock. \hyphpar0\par\pard\sb105\li300\ri300\sl240 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. \hyphpar0\par\pard\sb105\li300\ri300\sl240 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, \b cidr_addr_broadcast()\b0 and \b cidr_addr_network()\b0 will give answers as if it were a host-less subnet, while \b cidr_addr_hostmax()\b0 and \b cidr_addr_hostmin()\b0 will answer as though it were a 2-host subnet. It can be seen as a little strange for \b cidr_addr_broadcast()\b0 and \b cidr_addr_hostmax()\b0 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. \hyphpar0\par\pard\sb105\li300\ri300\sl240 Similar caveats apply to calling these on a v4 /32 or v6 /128. Ask a silly question, get a silly answer :) \hyphpar0\par\pard\sb105\li300\ri300\sl240 The returned structure should be cleaned up using \b cidr_free()\b0 . \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: A \b CIDR\b0 structure describing an arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to a \b CIDR\b0 structure describing the broadcast address on success. Returns NULL on failure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Given NULL\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_addr_broadcast()\b0 can also fail and set errno for any of the reasons listed for \b cidr_alloc()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_addr_hostmax(): \fs28 Find the highest host address \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Generate a \b CIDR\b0 structure describing the highest-numbered address available for a host IP in the given netblock. \hyphpar0\par\pard\sb105\li300\ri300\sl240 See the discussion under \b cidr_addr_broadcast()\b0 concerning near- amd maximal-prefix-length blocks for edge case details. \hyphpar0\par\pard\sb105\li300\ri300\sl240 The returned structure should be cleaned up using \b cidr_free()\b0 . \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: A \b CIDR\b0 structure describing an arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to a \b CIDR\b0 structure describing the max host address on success. Returns NULL on failure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_addr_hostmax()\b0 can fail and set errno for any of the reasons listed for \b cidr_addr_broadcast()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_addr_hostmin(): \fs28 Find the lowest host address \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Generate a \b CIDR\b0 structure describing the lowest-numbered address available for a host IP in the given netblock. \hyphpar0\par\pard\sb105\li300\ri300\sl240 See the discussion under \b cidr_addr_broadcast()\b0 concerning near- amd maximal-prefix-length blocks for edge case details. \hyphpar0\par\pard\sb105\li300\ri300\sl240 The returned structure should be cleaned up using \b cidr_free()\b0 . \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: A \b CIDR\b0 structure describing an arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to a \b CIDR\b0 structure describing the min host address on success. Returns NULL on failure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_addr_hostmin()\b0 can fail and set errno for any of the reasons listed for \b cidr_addr_network()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_addr_network(): \fs28 Find the network address \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Generate a \b CIDR\b0 structure describing the network address of the passed-in netblock. \hyphpar0\par\pard\sb105\li300\ri300\sl240 See the discussion under \b cidr_addr_broadcast()\b0 concerning near- amd maximal-prefix-length blocks for edge case details. \hyphpar0\par\pard\sb105\li300\ri300\sl240 The returned structure should be cleaned up using \b cidr_free()\b0 . \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: A \b CIDR\b0 structure describing an arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to a \b CIDR\b0 structure describing the network address on success. Returns NULL on failure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Given NULL\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_addr_network()\b0 can also fail and set errno for any of the reasons listed for \b cidr_alloc()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_alloc(): \fs28 Create a \b CIDR\b0 \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Allocate memory for a \b CIDR\b0 structure and initialize the necessary pieces. \hyphpar0\par\pard\sb105\li300\ri300\sl240 The returned structure should be cleaned up using \b cidr_free()\b0 . \hyphpar0\par\pard\sb105\li300\ri300\sl240 Note that you should probably never need to call this function yourself; you'll generally get your \b CIDR\b0 structures as a return from a function like \b cidr_from_str()\b0 or \b cidr_from_inaddr()\b0 . \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 None.\hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to an initialized \b CIDR\b0 structure on success. Returns NULL on failure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [ENOMEM]\keepn\hyphpar0\par\pard\li800\ri800\sl240 \b malloc()\b0 failed\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_contains(): \fs28 Compare netblocks \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 This function is passed two \b CIDR\b0 structures describing a pair of netblocks. It then determines if the latter is wholly contained within the former. \hyphpar0\par\pard\sb105\li300\ri300\sl240 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. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * big: The netblock which may (or may not) contain the second arg. \hyphpar0\par\pard\li300\ri300\sl240 - const \b CIDR\b0 * little: The netblock which may (or may not) be contained within the first arg. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 int\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns 0 if little is wholly contained within big. Returns -1 if it's not, or if an error occured. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [0]\keepn\hyphpar0\par\pard\li800\ri800\sl240 No error (little not in big)\hyphpar0\par\pard\li300\ri300\sl240 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 - [EINVAL]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Invalid argument\hyphpar0\par\pard\li300\ri300\sl240 - [ENOENT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Internal error (shouldn't happen)\hyphpar0\par\pard\li300\ri300\sl240 - [EPROTO]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Protocols don't match\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_dup(): \fs28 Duplicate a netblock \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Allocate a \b CIDR\b0 , and fill it in with a duplicate of the information given. \hyphpar0\par\pard\sb105\li300\ri300\sl240 The returned structure should be cleaned up using \b cidr_free()\b0 . \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * src: A \b CIDR\b0 structure to be copied. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a \b CIDR\b0 struct containing a copy of src. Returns NULL on failure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_dup()\b0 can fail and set errno for any of the reasons listed for \b cidr_alloc()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_equals(): \fs28 Compare two blocks for equality \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 This function is passed two \b CIDR\b0 structures describing a pair of netblocks. It checks to see if they happen to describe the same netblock. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * one: One netblock. \hyphpar0\par\pard\li300\ri300\sl240 - const \b CIDR\b0 * two: Another netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 int\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns 0 if the two \b CIDR\b0 structs describe the same netblock. Returns -1 otherwise. \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_free(): \fs28 Free a \b CIDR\b0 structure.\keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Takes a \b CIDR\b0 structure and \b free()\b0 's all its component parts. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - \b CIDR\b0 * tofree: A single \b CIDR\b0 structure which has outlived its usefulness. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 void\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_from_inaddr(): \fs28 Parse a struct in_addr \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Takes a populated struct in_addr, as you'd get from \b accept()\b0 or \b getaddrinfo()\b0 or similar functions. Parses it out and generates a \b CIDR\b0 structure based on it. Note that an in_addr only contains a host address, so the netmask is initialized to all-1's (/32). \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const struct in_addr * uaddr: A populated struct in_addr, from whatever source obtained. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to a populated \b CIDR\b0 containing the address in the passed-in struct in_addr. The netmask is initialized to all-1's, and the protocol to IPv4. Use \b cidr_free()\b0 to free the structure when you're finished with it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_from_inaddr()\b0 can also fail and set errno for any of the reasons listed for \b cidr_alloc()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_from_in6addr(): \fs28 Parse a struct in6_addr \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Takes a populated struct in6_addr, as you'd get from \b accept()\b0 or \b getaddrinfo()\b0 or similar functions. Parses it out and generates a \b CIDR\b0 structure based on it. Note that a in6_addr only contains a host address, so the netmask is initialized to all-1's (/128). \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const struct in6_addr * uaddr: A populated struct in6_addr, from whatever source obtained. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to a populated \b CIDR\b0 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 \b cidr_free()\b0 to free the structure when you're finished with it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_from_inaddr()\b0 can also fail and set errno for any of the reasons listed for \b cidr_alloc()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_from_str(): \fs28 Parse a human-readable string \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Takes in a netblock description as a human-readable string, and creates a \b CIDR\b0 structure from it. \hyphpar0\par\pard\sb105\li300\ri300\sl240 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. \hyphpar0\par\pard\sb105\li300\ri300\sl240 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). \hyphpar0\par\pard\sb105\li300\ri300\sl240 Also, \b cidr_from_str()\b0 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. \b cidr_from_str()\b0 also understands the deprecated RFC1886 form of IPv6 PTR records, which ends in .ip6.int, though \b cidr_to_str()\b0 will only generate the current RFC3152-style .ip6.arpa version. Note also that while \b cidr_to_str()\b0 treats all addresses as host addresses when building the PTR string (ignoring the netmask), \b cidr_from_str()\b0 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. \hyphpar0\par\pard\sb105\li300\ri300\sl240 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 \b cidr_contains()\b0 , or generating references and stats about a netblock with functions like \b cidr_addr_broadcast()\b0 and \b cidr_numhost()\b0 , or simply spitting it out in different human-readable forms with \b cidr_to_str()\b0 . \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const char * addr: A string containing some human-readable IP block. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to a populated \b CIDR\b0 describing (hopefully) the block you talked about in the string. Use \b cidr_free()\b0 to free the structure when you're finished with it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 - [EINVAL]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Can't parse the input string\hyphpar0\par\pard\li300\ri300\sl240 - [ENOENT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Internal error (shouldn't happen)\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_from_str()\b0 can also fail and set errno for any of the reasons listed for \b cidr_alloc()\b0 or \b cidr_get_pflen()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_get_addr(): \fs28 Return address bits \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Return the address bits which compose the address. This should be used in preference to simply referencing inside the \b CIDR\b0 manually in external code, since the structure might change on you. \hyphpar0\par\pard\sb105\li300\ri300\sl240 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 \b cidr_to_str()\b0 or one of the manipulation functions like \b cidr_addr_hostmin()\b0 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. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: An arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 uint8_t *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to an 16-element array of uint8_t's representing the address. This array must be \b free()\b0 'd when you're through with it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 - [ENOMEM]\keepn\hyphpar0\par\pard\li800\ri800\sl240 \b malloc()\b0 failed\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_get_mask(): \fs28 Return netmask bits \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Return the netmask bits which of the given netblock. This should be used in preference to simply referencing inside the \b CIDR\b0 manually in external code, since the structure might change on you. \hyphpar0\par\pard\sb105\li300\ri300\sl240 See further notes about the desirability of using this function above in the notes for \b cidr_get_addr()\b0 . \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: An arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 uint8_t *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to an 16-element array of uint8_t's representing the netmask. This array must be \b free()\b0 'd when you're through with it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 - [ENOMEM]\keepn\hyphpar0\par\pard\li800\ri800\sl240 \b malloc()\b0 failed\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_get_pflen(): \fs28 Network bits in the netmask \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Poke around the netmask of the passed-in \b CIDR\b0 structure and determine how many bits there are in the netmask, as appropriate to the address family. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * block: An arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 int\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns the number of network bits in the netmask (0-32 for IPv4, 0-128 for IPv6). Returns -1 on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 - [EINVAL]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Invalid (non-contiguous) netmask\hyphpar0\par\pard\li300\ri300\sl240 - [ENOENT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Internal error (shouldn't happen)\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_get_proto(): \fs28 Find a netblock's protocol family \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Returns the protocol family of an address using one of the defined constants. The current choices are CIDR_IPV4 and CIDR_IPV6. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: An arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 int\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns the address family of the given netblock. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_is_v4mapped(): \fs28 Is address IPv4-mapped IPv6 address? \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 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 \b CIDR\b0 is NOT considered an IPv4-mapped address, and so will return failure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: An arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 int\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns 0 if the address is an IPv4-mapped IPv6 address. Returns -1 otherwise. \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_net_subnets(): \fs28 Divide a netblock \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Take in a netblock, and derive the two netblocks which it divides up into. Return them in an array. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: The netblock to subdivide. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 **\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a 2-element array of \b CIDR\b0 structs, containing the two subnets of addr. Each of the elements should be cleaned up with \b cidr_free()\b0 , and the array itself then cleaned up with \b free()\b0 . Returns NULL on failure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [0]\keepn\hyphpar0\par\pard\li800\ri800\sl240 No error (already a /32 or /128)\hyphpar0\par\pard\li300\ri300\sl240 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL argument\hyphpar0\par\pard\li300\ri300\sl240 - [ENOMEM]\keepn\hyphpar0\par\pard\li800\ri800\sl240 \b malloc()\b0 failed\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_net_subnets()\b0 can also fail and set errno for any of the reasons listed for \b cidr_addr_network()\b0 or \b cidr_dup()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_net_supernet(): \fs28 Undivide a netblock \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Take in a netblock, and derive the parent netblock in which it fits. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: The netblock to find the parent of. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \b\fs28 CIDR\b0 *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a \b CIDR\b0 struct defining the parent network of addr. Clean this up with \b cidr_free()\b0 when you're finished with it. Returns NULL on failure. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [0]\keepn\hyphpar0\par\pard\li800\ri800\sl240 No error (already a /0)\hyphpar0\par\pard\li300\ri300\sl240 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL argument\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_net_supernet()\b0 can also fail and set errno for any of the reasons listed for \b cidr_dup()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_numaddr(): \fs28 Addresses in a netblock \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Determine the total number of addresses in a netblock (including the network and broadcast addresses). \hyphpar0\par\pard\sb105\li300\ri300\sl240 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? \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: An arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 const char *\hyphpar0\par\pard\sb105\li400\ri400\sl240 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 \b free()\b0 'd. Make a copy if you want to manipulate it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_numaddr()\b0 can also also fail and set errno for any of the reasons listed for \b cidr_numaddr_pflen()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_numaddr_pflen(): \fs28 Addresses in a prefix length \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Determine the total number of addresses in a netblock with the given prefix length (including the network and broadcast addresses). \hyphpar0\par\pard\sb105\li300\ri300\sl240 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. \hyphpar0\par\pard\sb105\li300\ri300\sl240 See the note in \b cidr_numaddr()\b0 for why we're returning a string and not a number. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - int pflen: A prefix length (0-128). \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 const char *\hyphpar0\par\pard\sb105\li400\ri400\sl240 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 \b free()\b0 'd. Make a copy if you want to manipulate it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EINVAL]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Invalid prefix length\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_numhost(): \fs28 Host addresses in a netblock \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Determine the total number of host addresses in a netblock (excluding the network and broadcast addresses). \hyphpar0\par\pard\sb105\li300\ri300\sl240 See the note in \b cidr_numaddr()\b0 for why we're returning a string and not a number. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: An arbitrary netblock. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 const char *\hyphpar0\par\pard\sb105\li400\ri400\sl240 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 \b free()\b0 'd. Make a copy if you want to manipulate it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_numhost()\b0 can also also fail and set errno for any of the reasons listed for \b cidr_numhost_pflen()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_numhost_pflen(): \fs28 Host addresses in a prefix length \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Determine the total number of host addresses in a netblock with the given prefix length (excluding the network and broadcast addresses). \hyphpar0\par\pard\sb105\li300\ri300\sl240 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. \hyphpar0\par\pard\sb105\li300\ri300\sl240 See the note in \b cidr_numaddr()\b0 for why we're returning a string and not a number. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - int pflen: A prefix length (0-128). \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 const char *\hyphpar0\par\pard\sb105\li400\ri400\sl240 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 \b free()\b0 'd. Make a copy if you want to manipulate it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EINVAL]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Invalid prefix length\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_to_inaddr(): \fs28 Create a struct in_addr \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Takes in a \b CIDR\b0 and creates a struct in_addr from it. This struct can then be used in \b connect()\b0 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. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: A \b CIDR\b0 structure describing the host to be translated into a struct in_addr. Note that the netmask is irrelevant and will be ignored. \b cidr_to_inaddr()\b0 supports only IPv4 addresses, as the underlying structure only does. \hyphpar0\par\pard\li300\ri300\sl240 - 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. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 struct in_addr *\hyphpar0\par\pard\sb105\li400\ri400\sl240 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 \b free()\b0 'd by the user when they're finished with it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 - [ENOMEM]\keepn\hyphpar0\par\pard\li800\ri800\sl240 \b malloc()\b0 failed\hyphpar0\par\pard\li300\ri300\sl240 - [EPROTOTYPE]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Bad protocol type (must be IPv4)\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_to_in6addr(): \fs28 Create a struct in6_addr \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Takes in a \b CIDR\b0 and creates a struct in6_addr from it. This struct can then be used in \b connect()\b0 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. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * addr: A \b CIDR\b0 structure describing the host to be translated into a struct in6_addr. Note that the netmask is irrelevant and will be ignored. \b cidr_to_in6addr()\b0 supports both IPv4 and IPv6 addresses, as the underlying structure does as well. IPv4 addresses are treated as v4-mapped IPv6 addresses. \hyphpar0\par\pard\li300\ri300\sl240 - 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. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 struct in6_addr *\hyphpar0\par\pard\sb105\li400\ri400\sl240 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 \b free()\b0 'd by the user when they're finished with it. Returns NULL on error. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EFAULT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Passed NULL\hyphpar0\par\pard\li300\ri300\sl240 - [ENOMEM]\keepn\hyphpar0\par\pard\li800\ri800\sl240 \b malloc()\b0 failed\hyphpar0\par\pard\li300\ri300\sl240 - [EPROTOTYPE]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Bad protocol type (must be IPv4 or IPv6)\hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_to_str(): \fs28 Create a human-readable netblock description \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Takes in a \b CIDR\b0 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. \hyphpar0\par\pard\sb105\li300\ri300\sl240 The current flags are: \hyphpar0\par\pard\li300\ri300\sl240 CIDR_NOFLAGS: A stand-in for when you just want the default output \hyphpar0\par\pard\li300\ri300\sl240 CIDR_NOCOMPACT: Don't do ::-style IPv6 compaction \hyphpar0\par\pard\li300\ri300\sl240 CIDR_VERBOSE: Show leading 0's in octets [v6 only] \hyphpar0\par\pard\li300\ri300\sl240 CIDR_USEV6: Use IPv4-mapped address form for IPv4 addresses (::ffff:a.b.c.d) \hyphpar0\par\pard\li300\ri300\sl240 CIDR_USEV4COMPAT: Use IPv4-compat form (::a.b.c.d) instead of IPv4-mapped form (only meaningful in combination with CIDR_USEV6) \hyphpar0\par\pard\li300\ri300\sl240 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. \hyphpar0\par\pard\li300\ri300\sl240 CIDR_ONLYADDR: Show only the address, without the prefix/netmask \hyphpar0\par\pard\li300\ri300\sl240 CIDR_ONLYPFLEN: Show only the prefix length (or netmask, when combined with CIDR_NETMASK), without the address. \hyphpar0\par\pard\li300\ri300\sl240 CIDR_WILDCARD: Show a Cisco-style wildcard mask instead of the netmask (only meaningful in combination with CIDR_NETMASK) \hyphpar0\par\pard\li300\ri300\sl240 CIDR_FORCEV6: Forces treating the \b CIDR\b0 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. \hyphpar0\par\pard\li300\ri300\sl240 CIDR_FORCEV4: Forces treating the \b CIDR\b0 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. \hyphpar0\par\pard\li300\ri300\sl240 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 \b cidr_from_str()\b0 for details of the asymmetric treatment of this form of address representation relating to the netmask. \hyphpar0\par\pard\sb105\li300\ri300\sl240 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. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - const \b CIDR\b0 * block: The \b CIDR\b0 structure to generate a string form of. The address family will be autodetected. \hyphpar0\par\pard\li300\ri300\sl240 - int flags: A bitmask of the various possible flags the function accepts. \hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 char *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to a string containing the representation of the network. Be sure to \b free()\b0 it when you're finished. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Error codes:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 - [EINVAL]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Invalid argument (bad block or flags)\hyphpar0\par\pard\li300\ri300\sl240 - [ENOENT]\keepn\hyphpar0\par\pard\li800\ri800\sl240 Internal error (shouldn't happen)\hyphpar0\par\pard\li300\ri300\sl240 - [ENOMEM]\keepn\hyphpar0\par\pard\li800\ri800\sl240 \b malloc()\b0 failed\hyphpar0\par\pard\li300\ri300\sl240 Note:\keepn\hyphpar0\par\pard\sb210\li800\ri800\sl240 \b cidr_to_str()\b0 can also fail and set errno for any of the reasons listed for \b cidr_alloc()\b0 or \b cidr_get_pflen()\b0 . \hyphpar0\par\pard\sb210\sl240 \fs35 - cidr_version(): \fs28 Library version \keepn\hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Summary:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 Returns a static string describing the library release version. \hyphpar0\par\pard\sb105\li200\ri200\sl240 \fs35 Arguments:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 None.\hyphpar0\par\pard\sb210\li200\ri200\sl240 \fs35 Return value:\keepn\hyphpar0\par\pard\sb105\li300\ri300\sl240 \fs28 const char *\hyphpar0\par\pard\sb105\li400\ri400\sl240 Returns a pointer to a static string describing the library version number. It shouldn't be overwritten or \b free()\b0 'd. \hyphpar0\par}
|
