Flyology API reference

Description

Resolves host names with nonblocking DNS transports and a bounded cache.

Example:

Addresses := Flyology.IO.DNS.Resolve ("example.net", Timeout => 2.0);

Address_Array

type Address_Array is
  array (Positive range <>) of GNAT.Sockets.Inet_Addr_Type;

Nonempty or null array of resolved internet addresses.

Clear_Cache

procedure Clear_Cache

Atomically remove all process-local positive and negative cache entries. The cache owns no descriptors or background tasks and is safe to use concurrently with resolution calls.

Family_Preference

type Family_Preference is (Any_Family, IPv4_Only, IPv6_Only);

Address families returned by the resolver.

Enumeration literals

Any_Family: Return available IPv6 and IPv4 addresses
IPv4_Only: Query or accept only IPv4 addresses
IPv6_Only: Query or accept only IPv6 addresses

Malformed_Response

Malformed_Response : exception;

Raised when no valid result can be obtained from malformed responses.

Name_Not_Found

Name_Not_Found     : exception;

Raised for a valid negative DNS answer or family mismatch.

Name_Server_Array

type Name_Server_Array is
  array (Positive range <>) of GNAT.Sockets.Sock_Addr_Type;

Caller-supplied numeric DNS endpoints for Resolve_Using.

Operation_Cancelled

Operation_Cancelled : exception;

Raised when a member of the resolver's interrupt set becomes readable.

Resolution_Failed

Resolution_Failed  : exception;

Raised for invalid resolver input or unusable resolver configuration.

Resolve

function Resolve
  (Name        : String;
   Family      : Family_Preference := Any_Family;
   Timeout     : Duration := 5.0;
   Interrupts  : Interrupt_Set := No_Interrupts;
   Configuration_Path : String := "/etc/resolv.conf")
   return Address_Array

Resolve through numeric servers in Configuration_Path. Search domains, ndots, retries, rotation, and bounded positive/negative caching are supported without libc name services. Numeric and localhost names bypass the file. Negative Timeout means no limit and zero is immediate; one deadline spans search candidates, family queries, retries, and transport fallback. Lightweight tasks suspend on socket readiness; native tasks block their threads. Reading Configuration_Path is a direct metadata operation and can block the underlying thread.

Parameters

Name: Host name, numeric address, or localhost
Family: Requested result family
Timeout: Overall deadline interval in seconds
Interrupts: Readable cancellation sources owned by the caller
Configuration_Path: Resolver configuration file

Return value

Resolved addresses in resolver response order

Raised exceptions

Name_Not_Found: No address exists for Name and Family
Resolution_Failed: Input or resolver configuration is unusable
Malformed_Response: Responses are malformed or inconsistent
Operation_Cancelled: An interrupt descriptor is readable
Timeout_Error: The overall deadline expires
Device_Error: Descriptor polling or transport setup fails
GNAT: .Sockets.Socket_Error A socket operation fails

Resolve_Using

function Resolve_Using
  (Name         : String;
   Name_Servers : Name_Server_Array;
   Family       : Family_Preference := Any_Family;
   Timeout      : Duration := 5.0;
   Attempts     : Positive := 2;
   Retry_Interval : Duration := 1.0;
   Interrupts     : Interrupt_Set := No_Interrupts)
   return Address_Array

Resolve through explicit numeric DNS endpoints without search-domain expansion. Timeout is one deadline across family queries, Attempts, and transports. Retry_Interval is the per-attempt interval. Lane and interrupt behavior match Resolve.

Parameters

Name: Host name, numeric address, or localhost
Name_Servers: Numeric UDP/TCP DNS endpoints
Family: Requested result family
Timeout: Overall deadline interval in seconds
Attempts: Attempts made for each query kind
Retry_Interval: Maximum seconds allocated per attempt
Interrupts: Readable cancellation sources owned by the caller

Return value

Resolved addresses in resolver response order

Raised exceptions

Name_Not_Found: No address exists for Name and Family
Resolution_Failed: Servers or retry interval are unusable
Malformed_Response: Responses are malformed or inconsistent
Operation_Cancelled: An interrupt descriptor is readable
Timeout_Error: The overall deadline expires
Device_Error: Descriptor polling or transport setup fails
GNAT: .Sockets.Socket_Error A socket operation fails