Implementation:ClickHouse ClickHouse Poco SocketAddress

Knowledge Sources	ClickHouse Poco Documentation
Domains	Networking, IP
Last Updated	2026-02-08 00:00 GMT

Overview

Representation of network endpoints combining IP addresses with port numbers for socket communication.

Description

The Poco `SocketAddress` class encapsulates a network endpoint consisting of an IP address (IPv4, IPv6, or UNIX domain socket path) and a port number. It provides constructors for creating addresses from various inputs (strings, `IPAddress` objects, native `sockaddr` structures), supports DNS resolution, service name lookup, and convenient string parsing.

The class handles both numeric and symbolic representations, parsing formats like "192.168.1.1:80", "[::1]:8080", or "example.com:http". For POSIX systems, it also supports UNIX local sockets with filesystem paths. The implementation uses the pimpl idiom for efficient copying and type erasure across address families.

Usage

ClickHouse uses this vendored component throughout its networking code to represent connection endpoints for both client and server sockets. It's used in socket binding, connection establishment, and peer address queries.

Code Reference

Source Location

• Repository: ClickHouse
• File: base/poco/Net/include/Poco/Net/SocketAddress.h
• Lines: 1-305

Signature

class SocketAddress {
public:
    typedef AddressFamily::Family Family;
    static const Family IPv4;
    static const Family IPv6;
    static const Family UNIX_LOCAL;

    SocketAddress();
    explicit SocketAddress(Family family);
    SocketAddress(const IPAddress& hostAddress, Poco::UInt16 portNumber);
    explicit SocketAddress(Poco::UInt16 port);
    SocketAddress(Family family, Poco::UInt16 port);
    SocketAddress(const std::string& hostAddress, Poco::UInt16 portNumber);
    SocketAddress(Family family, const std::string& hostAddress, Poco::UInt16 portNumber);
    SocketAddress(const std::string& hostAddress, const std::string& portNumber);
    SocketAddress(Family family, const std::string& hostAddress, const std::string& portNumber);
    explicit SocketAddress(const std::string& hostAndPort);
    SocketAddress(Family family, const std::string& addr);
    SocketAddress(const SocketAddress& addr);
    SocketAddress(const struct sockaddr* addr, poco_socklen_t length);

    SocketAddress& operator=(const SocketAddress& socketAddress);

    IPAddress host() const;
    Poco::UInt16 port() const;
    poco_socklen_t length() const;
    const struct sockaddr* addr() const;
    int af() const;
    std::string toString() const;
    Family family() const;

    bool operator<(const SocketAddress& socketAddress) const;
    bool operator==(const SocketAddress& socketAddress) const;
    bool operator!=(const SocketAddress& socketAddress) const;
};

Import

#include <Poco/Net/SocketAddress.h>

I/O Contract

Input	Output
IP address and port number	`SocketAddress` object
String ("host:port" or "[host]:port")	Parsed `SocketAddress` with DNS resolution
Service name (e.g., "http", "https")	`SocketAddress` with numeric port
Native `sockaddr` structure	Wrapped `SocketAddress` object

Address String Formats

Format	Example	Description
IPv4 with port	"192.168.1.1:80"	Dotted decimal IPv4 and numeric port
IPv6 with port	"[2001:db8::1]:8080"	Bracketed IPv6 hex notation and port
Hostname with port	"example.com:443"	DNS name and numeric port
Host with service	"example.com:https"	DNS name and service name
UNIX socket path	"/tmp/socket"	Local domain socket (POSIX)

Usage Examples

// Create from IP address and port
IPAddress ip("192.168.1.100");
SocketAddress addr1(ip, 8080);
std::cout << addr1.toString() << std::endl;  // 192.168.1.100:8080

// Create from string
SocketAddress addr2("www.example.com:80");
std::cout << "Resolved to: " << addr2.host().toString() << std::endl;

// IPv6 address
SocketAddress addr3("[::1]:8080");
std::cout << "IPv6: " << addr3.toString() << std::endl;

// Wildcard address (bind to all interfaces)
SocketAddress wildcard(8080);  // 0.0.0.0:8080

// Wildcard for specific family
SocketAddress wildcard6(SocketAddress::IPv6, 8080);  // [::]:8080

// Service name resolution
SocketAddress httpAddr("example.com", "http");
std::cout << "HTTP port: " << httpAddr.port() << std::endl;  // 80

// Specify address family for ambiguous cases
SocketAddress addr4(SocketAddress::IPv4, "localhost", 8080);

// Parse combined host:port string
SocketAddress addr5("192.168.1.1:9000");

// Access components
std::cout << "Host: " << addr5.host().toString() << std::endl;
std::cout << "Port: " << addr5.port() << std::endl;
std::cout << "Family: " << addr5.family() << std::endl;

// Access raw sockaddr for system calls
const struct sockaddr* sa = addr5.addr();
poco_socklen_t len = addr5.length();
int family = addr5.af();  // AF_INET or AF_INET6

// Compare addresses
SocketAddress a1("192.168.1.1:80");
SocketAddress a2("192.168.1.1:80");
SocketAddress a3("192.168.1.2:80");

if (a1 == a2) {
    std::cout << "Same address" << std::endl;
}

// Sort addresses
std::vector<SocketAddress> addrs = {
    SocketAddress("192.168.1.3:80"),
    SocketAddress("192.168.1.1:80"),
    SocketAddress("192.168.1.2:80")
};
std::sort(addrs.begin(), addrs.end());

// UNIX domain socket (on POSIX systems)
#ifdef POCO_OS_FAMILY_UNIX
SocketAddress unixAddr(SocketAddress::UNIX_LOCAL, "/tmp/my.sock");
std::cout << "UNIX socket: " << unixAddr.toString() << std::endl;
#endif

// Handle parsing errors
try {
    SocketAddress badAddr("invalid:address:format");
} catch (const Poco::Exception& ex) {
    std::cerr << "Parse error: " << ex.displayText() << std::endl;
}

Related Pages

• Principle:ClickHouse_ClickHouse_Network_Address_Representation