# FBB::Cidr(3bobcat)

## CIDR matching
(libbobcat-dev_6.06.02)

## 2005-2024

## NAME

FBB::Cidr - Compares IP4 addresses to CIDR specifications

## SYNOPSIS

#include <bobcat/cidr>
Linking option: -lbobcat

## DESCRIPTION

Objects of the class Cidr can be used for testing whether IP4 Internet addresses belong to address ranges defined by Classless Inter-Domain Routing (CIDR) address block specifications. CIDR blocks are specified as a.b.c.d/m where a.b.c.d are the four octets of a dotted decimal IP4 address specification (e.g., 129.125.14.80) and m is a mask-size (ranging from 0 to 32) defining the number of most significant bits to remain as-is. The CIDR specification 129.125.14.80/16 defines a class B network, with addresses ranging from 129.125.0.0 to 129.125.255.255.

The mask size does not have to be a multiple of 8. E.g., when specifying 129.125.14.80/5 only the most significant 5 bits of the first octed are fixed, resulting in an address range ranging from 128.0.0.0 to 135.255.255.255.

CIDR specifications passed to a Cidr object must be of the form a.b.c.d or a.b.c.d/m. If the mask is not specified a mask-size of 32 is used, effectively defining an address range of only one address. Mask values of 0 are ignored. Mask values of 0 are ignored by Cidr objects.

When specifying CIDRs on a stream, empty lines and comment lines (having a hash-character (#) as their first non-blank character) are ignored. Non-empty lines must start with a CIDR specification, and the Cidr object will ignore all information on a line trailing a CIDR specification.

## NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

## INHERITS FROM

-

## CONSTRUCTORS

- Cidr(std::string const &cidrPattern):
  The Cidr object is initialized with a single CIDR specification.

- Cidr(std::istream &cidrStream):
  The Cidr object is initialized with CIDR specifications read from the std::istream cidrStream.

Default, copy and move constructors and the copy and move assignment operators are available.

## MEMBER FUNCTIONS

The return valuess of the accessors (i.e., the const members) are only defined following a successful match (see below, the match members).

- std::string const &address() const:
  returns the address matching a CIDR.

- std::string cidr() const:
  returns the CIDR containing a specified address.

- std::string first() const:
  returns the first address of the range of addresses defined by the CIDR specification.

- std::string last() const:
  returns the last address of the range of addresses defined by the CIDR specification. Note that first, last do not define an iterator range. The address returned by last still belongs to the CIDR-range.

- bool match(std::istream &in):
  The value true is returned when an IP4 address found in the lines of in belongs to a CIDR range inspected by the Cidr object. The match function returns true at the first matching address. E.g., if a line contains the text

          This is address 1.2.3.4 and this is 5.6.7.8

  and the CIDR specifications

              5.1.1.1/8
              1.2.1.1/16

  were provided to the Cidr object, then the object will report a match for 5.6.7.8.

  As soon as a match is found match returns true. If none of the addresses found in the lines of in matches any of the object's CIDR specifications, false is returned.

- std::string mask() const:
  returns the mask used by the CIDR specification.

- bool match(std::string const &line):
  The value true is returned when an IP4 address found in line belongs to a CIDR range inspected by the Cidr object. The match function returns true at the first matching address.

  If none of the addresses found in line matches any of the object's CIDR specifications, false is returned.

- void setCidr(std::istream &cidrStream):
  A new set of CIDR specification is loaded into the Cidr object, reading the specifications from cidrStream.

- void setCidr(std::string const &cidrPattern):
  A new CIDR specification is loaded into the Cidr object, using the specification found in cidrPattern. The Cidr object is initialized with a single CIDR specification which must be of the form a.b.c.d or a.b.c.d/m. If the mask is not specified a mask-size of 32 is used, effectively defining an address range of only one address. Mask values of 0 are ignored.

- void swap(Cidr &other):
  The current and other object are swapped.

## STATIC MEMBERS

- size_t dotted2binary(std::string const &dotted):
  Converts "a.b.c.d" to a 32-bits value

- std::string binary2dotted(size_t binary):
  Converts a 32-bits value to a dotted decimal IP4 address

## EXAMPLE

    #include <fstream>
    #include <iostream>

    #include <bobcat/exception>
    #ifdef BOBCAT
        #include <bobcat/cidr>
    #else
        #include "cidr"
    #endif

    using namespace std;
    using namespace FBB;

    int main(int argc, char **argv)
    {
        enum Spec
        {
            NONE,
            FILE,
            CIN
        };

        Spec spec = CIN;
        ifstream in;

        if (argc > 1)
        {
            Exception::open(in, argv[1]);       // file containing cidr-specs
            spec = FILE;
        }

        while (true)
        {
            string cidrSpec;
            if (spec == CIN)
            {
                cout << "Specify cidr (empty to quit): ";
                if (!getline(cin, cidrSpec) || cidrSpec.empty())
                    break;
            }
            try
            {
                Cidr cidr;

                switch (spec)
                {
                    case NONE:
                    return 0;

                    case FILE:
                        cidr.setCidr(in);
                        spec = NONE;
                    break;

                    case CIN:
                        cidr.setCidr(cidrSpec);
                }

                while (true)
                {
                    cout << "Specify address to test (empty to " <<
                        (spec == CIN ? "respec. CIDR" : "quit") << "): ";
                    string address;
                    if (!getline(cin, address) || address.empty())
                        break;

                    if (!cidr.match(address))
                    {
                        cout << "Address " << address << " not in ";
                        if (spec == CIN)
                            cout << cidrSpec << '\n';
                        else
                            cout << "specifications in " << argv[1] << '\n';
                    }
                    else
                        cout << "Address " << address << " in " << cidr.cidr() <<
                                                                            "\n"
                            "Lowest address: " << cidr.first() << "\n"
                            "Highest address: " << cidr.last() << "\n"
                            "CIDR mask: " << cidr.mask() << "\n"
                            "Address: " << cidr.address() << '\n';
                }
            }
            catch (exception const &err)
            {
                cout << "Oops... " << err.what() << "\n"
                        "Try again...\n";
            }
        }
    }

## FILES

bobcat/cidr - defines the class interface

## SEE ALSO

bobcat(7)

## BUGS

Members of Cidr use static data. The current implementation of Cidr is therefore not thread-safe.

## BOBCAT PROJECT FILES

- https://fbb-git.gitlab.io/bobcat/: gitlab project page;
- bobcat_6.06.02-x.dsc: detached signature;
- bobcat_6.06.02-x.tar.gz: source archive;
- bobcat_6.06.02-x_i386.changes: change log;
- libbobcat1_6.06.02-x_*.deb: debian package containing the libraries;
- libbobcat1-dev_6.06.02-x_*.deb: debian package containing the libraries, headers and manual pages;

## BOBCAT

Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

## COPYRIGHT

This is free software, distributed under the terms of the GNU General Public License (GPL).

## AUTHOR

Frank B. Brokken (f.b.brokken@rug.nl).