IP Addresses

7.7

top ← prev up next →

IP Addresses

Bogdan Popa <bogdan@defn.io>

(require net/ip)

package: net-ip-lib

1 Introduction

This package provides utilities for working with IP addresses and networks in Racket.

2 Generic IP Addresses and Networks

All IP addresses and network versions support the operations that follow.

procedure
(make-ip-address ip) → ip-address?
  ip : string?
procedure
(make-ip-address ip) → ip-address?
  ip : bytes?
procedure
(make-ip-address ip version) → ip-address?
  ip : exact-nonnegative-integer?
  version : (or/c 4 16)

Parse an IP address.

IPv4 examples:

> (require net/ip)
> (make-ip-address "127.0.0.1")
(make-ip-address "127.0.0.1")
> (make-ip-address #"\177\0\0\1")
(make-ip-address "127.0.0.1")
> (make-ip-address 127 4)
(make-ip-address "0.0.0.127")

IPv6 examples:

> (require net/ip)
> (make-ip-address "::1")
(make-ip-address "0:0:0:0:0:0:0:1")
> (make-ip-address #"\377\377\0\0\0\0\0\0\0\0\0\0\0\0\0\0")
(make-ip-address "ffff:0:0:0:0:0:0:0")
> (make-ip-address "2001:db8::1")
(make-ip-address "2001:db8:0:0:0:0:0:1")

procedure
(make-network ip prefix) → network?
  ip : (or/c ip-address? string?)
  prefix : exact-nonnegative-integer?
procedure
(make-network ip mask) → network?
  ip : (or/c ip-address? string?)
  mask : (or/c ip-address? string?)
procedure
(make-network cidr) → network?
  cidr : string?

Parse a network.

IPv4 examples:

> (require net/ip)
> (make-network "192.168.1.0/24")
(make-network "192.168.1.0/24")
> (make-network "192.168.1.0" 24)
(make-network "192.168.1.0/24")
> (make-network "192.168.1.0" "255.255.255.0")
(make-network "192.168.1.0/24")
> (make-network (make-ip-address "192.168.1.0") 24)
(make-network "192.168.1.0/24")

IPv6 examples:

> (require net/ip)
> (make-network "::1/128")
(make-network "0:0:0:0:0:0:0:1/128")
> (make-network "::1" 128)
(make-network "0:0:0:0:0:0:0:1/128")
> (make-network "::1" "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff")
(make-network "0:0:0:0:0:0:0:1/128")
> (make-network (make-ip-address "::1") 128)
(make-network "0:0:0:0:0:0:0:1/128")

2.1 IP Address Operations

procedure
(ip-address? addr) → boolean?
addr : any/c

Return #t when addr is an IP address.

procedure
(ip-address=? addr other) → boolean?
  addr : ip-address?
  other : ip-address?
procedure
(ip-address<? addr other) → boolean?
  addr : ip-address?
  other : ip-address?
procedure
(ip-address<=? addr other) → boolean?
  addr : ip-address?
  other : ip-address?
procedure
(ip-address>? addr other) → boolean?
  addr : ip-address?
  other : ip-address?
procedure
(ip-address>=? addr other) → boolean?
  addr : ip-address?
  other : ip-address?

Compare addr and other. These functions raise exn:fail:contract? when the two addresses are of different versions.

procedure
(ip-address-bitcount addr) → exact-nonnegative-integer?
addr : ip-address?

Count the number of set high bits in addr.

Examples:

> (require net/ip)
> (ip-address-bitcount (make-ip-address "0.0.0.0"))
0
> (ip-address-bitcount (make-ip-address "255.255.255.0"))
24
> (ip-address-bitcount (make-ip-address "255.255.255.255"))
32
> (ip-address-bitcount (make-ip-address "ffff::"))
16

procedure
(ip-address-dec addr [n]) → ip-address?
addr : ip-address?
n : exact-nonnegative-integer? = 1

Return an ip-address? smaller than addr by n. Raises exn:fail:contract? if the resulting address would be smaller than 0.

procedure
(ip-address-inc addr [n]) → ip-address?
addr : ip-address?
n : exact-nonnegative-integer? = 1

Return an ip-address? greater than addr by n. Raises exn:fail:contract? if the resulting address would be greater than the maximum address for that particular version.

procedure
(ip-address-size addr) → (or/c 32 128)
addr : ip-address?

Return 32 or 128 depending on the version of addr. This number represents the size in bits of each type of address.

procedure
(ip-address-version addr) → (or/c 4 6)
addr : ip-address?

Return 4 or 6 depending on the version of addr.

procedure
(ip-address->bytes addr) → bytes?
addr : ip-address?

Pack addr into an array of bytes in network order (big endian).

procedure
(ip-address->number addr) → exact-nonnegative-integer?
addr : ip-address?

Convert addr to a number.

procedure
(ip-address->string addr) → string?
addr : ip-address?

Convert addr to a string.

2.2 Network Operations

procedure
(network? net) → boolean?
net : any/c

Return #t when net is a network.

procedure
(network addr prefix) → network?
addr : ip-address?
prefix : exact-nonnegative-integer?

Construct a network from addr and prefix. Raises exn:fail:contract? if prefix is too large for addr.

procedure
(network-address net) → ip-address?
net : network?

Return the network address for net.

procedure
(network-prefix net) → exact-nonnegative-integer?
net : network?

Return the prefix for net.

procedure
(network-hostmask net) → ip-address?
net : network?

Return the host mask for net.

procedure
(network-netmask net) → ip-address?
net : network?

Return the net mask for net.

procedure
(network-size net) → exact-nonnegative-integer?
net : network?

Return the total number of ip addresses in net.

procedure
(network-member net addr) → boolean?
net : network?
addr : ip-address?

Return #t if addr is a member of net.

procedure
(network-version net) → (or/c 4 6)
net : network?

Return 4 or 6 depending on the version of net.

procedure
(network->string net) → string?
net : network?

Convert net to a string.

procedure
(network->stream net) → (stream/c ip-address?)
net : network?

Convert net to a stream of all the ip addresses contained inside it.

3 IPv4

These functions are specific to IPv4 addresses.

3.1 IPv4 Addresses

procedure
(ipv4-address? addr) → boolean?
addr : any/c

Return #t when addr is an IPv4 address.

procedure
(bytes->ipv4-address bs) → ipv4-address?
bs : bytes?

Unpack a byte array in network order (big endian) into an IPv4 address. Must be exactly four bytes long,otherwise an exn:fail:contract? is raised.

procedure
(number->ipv4-address value) → ipv4-address?
value : exact-nonnegative-integer?

Return the IPv4 address represented by value. value must be between 0 and 2^32-1, otherwise an exn:fail:contract? is raised.

procedure
(string->ipv4-address ip) → ipv4-address?
ip : string?

Parse an IPv4 address. Includes support for compressed notation, similar to what is available on most UNIX systems.

Examples:

> (require net/ip)
> (string->ipv4-address "127.0.0.1")
(make-ip-address "127.0.0.1")
> (string->ipv4-address "127.1")
(make-ip-address "127.0.0.1")
> (string->ipv4-address "192.168.1")
(make-ip-address "192.168.0.1")

4 IPv6

These functions are specific to IPv6 addresses.

4.1 IPv6 Addresses

procedure
(ipv6-address? addr) → boolean?
addr : any/c

Return #t when addr is an IPv6 address.

procedure
(bytes->ipv6-address ip) → ipv6-address?
ip : bytes?

Unpack a byte array in network order (big endian) into an IPv6 address. Must be exactly sixteen bytes long, otherwise an exn:fail:contract? is raised.

procedure
(number->ipv6-address value) → ipv6-address?
value : exact-nonnegative-integer?

Return the IPv6 address represented by value. value must be between 0 and 2^128-1, otherwise an exn:fail:contract? is raised.

procedure
(string->ipv6-address ip) → ipv6-address?
ip : string?

Parse an IPv6 address.

Examples:

> (require net/ip)
> (string->ipv6-address "::1")
(make-ip-address "0:0:0:0:0:0:0:1")
> (string->ipv6-address "ff:ab:cd::ff")
(make-ip-address "ff:ab:cd:0:0:0:0:ff")
> (string->ipv6-address "201:db:ee::1")
(make-ip-address "201:db:ee:0:0:0:0:1")
> (string->ipv6-address "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff")
(make-ip-address "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff")

top ← prev up next →