RGXG_NET_CIDR_STRING(3)

NAME
rgxg_net_cidr_string, rgxg_net_cidr_ipv4, rgxg_net_cidr_ipv6 - create regex that matches all addresses of the given CIDR block

SYNOPSIS
#include <rgxg/net.h>

int rgxg_net_cidr_string (const char *cidr, char **endptr, char *regex,
rgxg_options_t options);

int rgxg_net_cidr_ipv4 (const rgxg_ipv4_t *address, int prefix, char *regex,
rgxg_options_t options);
int rgxg_net_cidr_ipv6 (const rgxg_ipv6_t *address, int prefix, char *regex,
rgxg_options_t options);

DESCRIPTION
rgxg_net_cidr_string() generates the (extended) regular expression that matches all addresses of the CIDR block given as string in cidr (e.g. "192.168.0.0/24" or "2001:db8:aaaa::/64"). cidr must be valid and not NULL.

If endptr is not NULL, rgxg_net_cidr_string() stores on success the address of the first character which is not part of the CIDR block in *endptr. If there is no error and **endptr is '\0', then the entire string has been parsed. The *endptr values in case of an error are described in the ERRORS section below.

rgxg_net_cidr_ipv4() and rgxg_net_cidr_ipv6() generate the (extended) regular expression that matches all addresses of the CIDR block specified by address and prefix (network identifier), which must be between 0 and 32 (rgxg_net_cidr_ipv4()) respectively 128 (rgxg_net_cidr_ipv6()) inclusive. address must be valid and not NULL.

The rgxg_ipv4_t and rgxg_ipv6_t structures which are the types of address are defined in <rgxg/net.h>.

typedef struct {
    uint8_t octet[4];
} rgxg_ipv4_t;

typedef struct {
    uint16_t hextet[8];
} rgxg_ipv6_t;

The n-th element of the octet/hextet array stores the (n+1)-th octet/hextet of the IPv4 respectively IPv6 address (i.e. for instance the first octet '192' in '192.168.0.0' is stored in octet[0]).

The generated regular expression is written to the character string regex, including the terminating null byte ('\0'), unless RGXG_NONULLBYTE is set. If regex is NULL the return value is the number of characters (excluding the terminating null byte) that would have been written in case regex has been initialized. Note that the functions assume an arbitrarily long regex string, callers must ensure that the given string is large enough to not overflow the actual space.

options is either zero, or the bitwise-or of one or more of the following macros:

Options marked as 'IPv6 only' can be used with rgxg_net_cidr_string() (when parsing IPv6 CIDR blocks) and with rgxg_net_cidr_ipv6().

RGXG_NOUPPERCASE (IPv6 only)
    The generated regular expression only matches IPv6 addresses with lower case letters. By default both lower and upper case letters are matched.

RGXG_NOLOWERCASE (IPv6 only)
    The generated regular expression only matches IPv6 addresses with upper case letters. By default both lower and upper case letters are matched.

RGXG_NOZEROCOMPRESSION (IPv6 only)
    The generated regular expression does not match IPv6 addresses with zero compression (second form of text representation of IPv6 addresses mentioned in section 2.2 of RFC 4291).

RGXG_NOMIXEDNOTATION (IPv6 only)
    The generated regular expression does not match IPv6 addresses in mixed notation (third form of text representation of IPv6 addresses mentioned in section 2.2 of RFC 4291).

RGXG_NOOUTERPARENS (IPv6 only)
    Omit the outer parenthesis, if any, of the regular expression.

RGXG_NONULLBYTE
    Do not add the terminating null byte ('\0') to the regex string.

Note that RGXG_NOUPPERCASE and RGXG_NOLOWERCASE are mutual exclusive options.

RETURN VALUE

Upon successful return, these functions return the number of characters (excluding the terminating null byte) written to regex.

If an error occurs, a (negative) error code is returned (see ERRORS section).

ERRORS
The following errors can be returned:

RGXG_ERROR_PREFIX
    Invalid network identifier (e.g. the prefix is lesser than 0 or greater than 32 (IPv4) respectively 128 (IPv6)).

    rgxg_net_cidr_string(): If endptr is not NULL, *endptr points to the first character of the invalid prefix.

RGXG_ERROR_ARG2BIG (rgxg_net_cidr_string() only)
    At least one octet/hextet is too large.

    rgxg_net_cidr_string(): If endptr is not NULL, *endptr points to the first digit of the too large octet/hextet.

RGXG_ERROR_SYNTAX (rgxg_net_cidr_string() only)
    Syntax error in cidr string. If endptr is not NULL, *endptr points to the character that causes the syntax error.

RGXG_ERROR_MUTEXOPTIONS (rgxg_net_cidr_string()/rgxg_net_cidr_ipv6() only)
    Two mutual exclusive options were specified.

AVAILABILITY
These functions are available since rgxg 0.1.

SEE ALSO
regex(7), rgxg_number_greaterequal(3), rgxg_number_range(3).

AUTHOR
Hannes von Haugwitz <hannes@vonhaugwitz.com>