Merge pull request #420 from sshanks-kx/ip

improve .z.a/.z.h/.Q.host/.Q.addr details

Author: iciobanukx

docs/ref/dotq.md

@@ -126,25 +126,61 @@ q).Q.addmonths[2006.10.29;4]
 .Q.addr x
 ```
 
-Where `x` is a hostname or IP address as a symbol atom, returns the IP address as an integer (same format as [`.z.a`](dotz.md#za-ip-address))
+Where `x` is a hostname or IP address as a symbol atom, returns the IP address as an integer.
 
+The dotted-decimal string representation can be obtained from an integer using [`vs`](vs.md#integer-based-ip-address).
+
+If the symbol represents a standard IPv4 dotted decimal notation, it returns the IP as integer without any DNS look-ups required.
 ```q
-q).Q.addr`localhost
+q).Q.addr`$"127.0.0.1"
 2130706433i
-q).Q.host .Q.addr`localhost
-`localhost
+```
+
+When given a host name, the underlying operating system will govern how the look-up occurs. The IP address will be returned as an integer.
+
+```q
 q).Q.addr`localhost
 2130706433i
-q)256 vs .Q.addr`localhost
-127 0 0 1
+```
+If the host cannot be resolved, -1 will be returned
+```q
+q).Q.addr`blah
+-1i
 ```
 
-:fontawesome-regular-hand-point-right:
-[`.Q.host`](#host-ip-to-hostname) (IP to hostname)
-<br>
-:fontawesome-solid-book-open:
-[`vs`](vs.md)
+Each underlying operating system deals with IP to hostname (and vice-versa) in different ways.
+
+**Linux**
+
+Consults `/etc/nsswitch.conf` to find the `host` entry (consult the man page on `/etc/nsswitch.conf` for further details).
+This configuration and look-up order can be different for each distribution. For example, an entry may exist for the following:
+
+* `hosts` consults `/etc/hosts` which can contain multiple hostnames for a given IP
+* `dns` use DNS resolver (`/etc/resolv.conf`)
+
+Return first entry found to match the provided IP.
+
+**MacOS**
+
+Returns first entry found when consulting the following:
+
+* `/etc/hosts` which can contain multiple hostnames for a given IP
+* consults system settings
+* consults [mDNSResponder](https://github.com/apple-oss-distributions/mDNSResponder)
+
+**Microsoft Windows**
+These can be adjusted by system settings or policies, but typical order is:
+
+* check Windows DNS Client Service (dnscache) for recent query result
+* check hosts file `C:\Windows\System32\drivers\etc\hosts`
+* reverse dns
+* optionally configured services, for example NetBIOS/LLMNR/WINS
 
+If multiple addresses available, it uses a [prefix policy table](https://learn.microsoft.com/en-us/troubleshoot/windows-server/networking/configure-ipv6-in-windows) 
+and dynamically adjusts preference based on interface reachability and past success.
+
+:fontawesome-regular-hand-point-right:
+[`.Q.host`](#host-ip-to-hostname) (IP to hostname), [`.z.h`](dotz.md#zh-host) (host), [`.z.a`](dotz.md#za-ip-address) (IP address), [`vs`](vs.md#byte-representation) (Byte representation)
 
 ## `b6` (bicameral-alphanums)
 
@@ -1160,21 +1196,51 @@ The server then decides whether to gzip the returned payload, which is uncompres
 Where `x` is an IP address as an int atom, returns its hostname as a symbol atom.
 
 ```q
-q).Q.host .Q.addr`localhost
+q).Q.host 2130706433i
 `localhost
-q).Q.addr`localhost
-2130706433i
+```
 
+The operator [`$`](tok.md#ip-address) (tok) can be used to convert an IP address in dotted-decimal string representation to an integer
+```q
 q)"I"$"104.130.139.23"
 1753385751i
 q).Q.host "I"$"104.130.139.23"
 `netbox.com
-q).Q.addr `netbox.com
-1753385751i
+```
+
+Each underlying operating system deals with resolving a hostname to IP (and vice-versa) in different ways, reference [`.Q.addr`](#addr-iphost-as-int) for details.
+
+When the resolving leads to consulting a DNS server, the DNS server can also have rules on which IP (or the sort order of IPs) it can return when multiple IPs associated with one host. 
+Therefore performing an IP lookup from a given hostname, then using the resuling IP to get its hostname, can return a different hostname. 
+For example:
+
+```q
+q).Q.host .Q.addr `$"www.yahoo.co.uk"
+`a7de0457831fd11f7.awsglobalaccelerator.com   / alternative hostname for IP
+```
+
+When using `/etc/hosts` on MacOS/Linux, the order in which multiple hosts are associated with an IP will effect the value returned.
+For example, `/etc/hosts` with the entry
+```bash
+172.17.0.4      test1 test2
+```
+will cause 172.17.0.4 to be resolved to test1
+```q
+q).Q.host "I"$"172.17.0.4"
+`test1
+```
+but `/etc/hosts` with the machine names in a different order
+```bash
+172.17.0.4      test2 test1
+```
+will cause 172.17.0.4 to be resolved to test2
+```q
+q).Q.host "I"$"172.17.0.4"
+`test2
 ```
 
 :fontawesome-regular-hand-point-right:
-[`.Q.addr`](#addr-iphost-as-int) (IP/host as int), [`$`](tok.md#ip-address) tok (IP address as int)
+[`.Q.addr`](#addr-iphost-as-int) (IP/host as int), [`.z.h`](dotz.md#zh-host) (host), [`.z.a`](dotz.md#za-ip-address) (IP address)
 
 
 ## `hp` (HTTP post)

docs/ref/dotz.md

@@ -77,39 +77,39 @@ q).z.a
 -1408172030i
 ```
 
-Note its relationship to [`.z.h`](#zh-host) for the hostname, converted to an int using [`.Q.addr`](dotq.md#host-ip-to-hostname).
-```q
-q).Q.addr .z.h
--1408172030i
-```
-
-It can be split into components as follows:
-
-```q
-q)"i"$0x0 vs .z.a
-172 17 0 2i
-```
-
-When invoked inside a `.z.p*` callback via a TCP/IP connection, it is the IP address of the client session, not the current session. For example, connecting from a remote machine:
-
-```q
-q)h:hopen myhost:1234
-q)h"\"i\"$0x0 vs .z.a"
-192 168 65 1i
-```
-or from same machine:
-```q
-q)h:hopen 1234
-q)h"\"i\"$0x0 vs .z.a"
-127 0 0 1i
-```
-
-When invoked via a Unix Domain Socket, it is 0.
-```q
-q)h:hopen `:unix://1234
-q)h".z.a"
-0i
-```
+The dotted-decimal string representation can be obtained from an integer using [`vs`](vs.md#integer-based-ip-address).
+
+The return value depends on whether it is invoked in an IPC callback or not.
+
+* **Not invoking in an IPC callback**
+   <br>Returns the current IP address associated with the hostname.
+   <br>This pre-populated value is equivalent to passing [`.z.h`](#zh-host) to [`.Q.addr`](dotq.md#host-ip-to-hostname) to find the IP address of the current host.
+   ```q
+   q).z.a
+   -1408172030i
+   q).Q.addr .z.h
+   -1408172030i
+   ```
+* **Invoking in an IPC callback**
+   <br>When invoked inside a `.z.p*` callback via a TCP/IP connection, it is the IP address of the client session, not the current session.
+   For example, connecting from a remote machine:
+   ```q
+   q)h:hopen myhost:1234
+   q)h"\"i\"$0x0 vs .z.a"
+   192 168 65 1i
+   ```
+   or from same machine:
+   ```q
+   q)h:hopen 1234
+   q)h"\"i\"$0x0 vs .z.a"
+   127 0 0 1i
+   ```
+   When invoked via a Unix Domain Socket, it is 0.
+   ```q
+   q)h:hopen `:unix://1234
+   q)h".z.a"
+   0i
+   ```
 
 :fontawesome-solid-hand-point-right:
 [`.z.h`](#zh-host) (host), [`.Q.host`](dotq.md#host-ip-to-hostname) (IP to hostname)
@@ -351,33 +351,26 @@ q).z.h
 `demo.kx.com
 ```
 
-On Linux this should return the same as the shell command `hostname`. If you require a fully qualified domain name, and the `hostname` command returns a hostname only (with no domain name), this should be resolved by your system administrators. Often this can be traced to the ordering of entries in `/etc/hosts`, e.g.
+If you require a fully qualified domain name, and the command returns a hostname only (with no domain name), this should be resolved by your system administrators. 
 
-Non-working `/etc/host` looks like :
+**Linux**
 
-```txt
-127.0.0.1    localhost.localdomain localhost
-192.168.1.1  myhost.mydomain.com myhost
-```
+On Linux this should return the same value as the shell command `hostname`. 
+Linux stores the current hostname in `/proc/sys/kernel/hostname`. The operating system reads the hostname from `/etc/hostname`.
 
-Working one has this ordering :
+**MacOS**
 
-```txt
-127.0.0.1    localhost.localdomain localhost
-192.168.1.1  myhost myhost.mydomain.com
-```
+On MacOS this should return the same value as `sysctl kern.hostname` or `scutil --get HostName`.
 
-One solution seems to be to flip around the entries, i.e. so the entries should be
+**Microsoft Windows**
 
-```txt
-ip hostname fqdn
+On Windows this should return the same value as `hostname` via cmd.exe or Powershell, 
+which typically gets the hostname from the registry entry `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ComputerName\ActiveComputerName`.
+The `req query` command can be used to retrieve the current value.
 ```
-
-A workaround from within kdb+ is
-
-```q
-q).Q.host .z.a
+reg query HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ComputerName\ActiveComputerName
 ```
+The value can also be viewed and altered via the Control Panel.
 
 :fontawesome-solid-hand-point-right:
 [`.z.a`](#za-ip-address) (IP address), [`.Q.addr`](dotq.md#addr-iphost-as-int) (IP/host as int)

docs/ref/tok.md

@@ -83,7 +83,7 @@ q)"D"$"2147483648"
 
     Short converts to 0Nh instead of +/-0Wh 
 
-## :fontawesome-solid-sitemap: Iteration
+## Iteration
 
 Tok is a near-[atomic function](../basics/atomic.md).
 Implicit recursion stops at strings, not atoms.
@@ -153,17 +153,24 @@ q)"b"$" ",.Q.an
 ```q
 q)"I"$"192.168.1.34" /an IP address as an int
 -1062731486i
-q)"NT"$\:"123456123987654"  / since V3.4
-0D12:34:56.123987654
-12:34:56.123
 ```
 
 :fontawesome-solid-book:
-[`.Q.addr`](dotq.md#addr-iphost-as-int),
-[`.Q.host`](dotq.md#host-ip-to-hostname)
+[`.Q.addr`](dotq.md#addr-iphost-as-int) (IP/host as int),
+[`.Q.host`](dotq.md#host-ip-to-hostname) (IP to hostname)
+
+## Timestamps
+
+### Raw numeric timestamps
 
+```q
+q)"N"$"123456123987654"
+0D12:34:56.123987654
+q)"T"$"123456123987654"
+12:34:56.123
+```
 
-## Unix timestamps
+### Unix timestamps
 
 (from seconds since Unix epoch), string with 9…11 digits:
 

docs/ref/vs.md

@@ -152,10 +152,20 @@ q)0x0 vs 2413e
 0x4516d000
 q)0x0 vs 2413f
 0x40a2da0000000000
-q)"."sv string"h"$0x0 vs .z.a / ip address string from .z.a
-"192.168.1.213"
 ```
 
+#### Integer based IP address
+
+Base-256 is used to encode IP addresses to integers. The following example converts the current IP address reported by [`.z.a`](dotz.md#za-ip-address)
+```q
+q)"i"$0x0 vs .z.a
+192 168 0 3i
+```
+The commonly written dotted-decimal notation can be produced from the list of longs using [`string`](string.md) and [`sv`](sv.md#strings).
+```q
+q)"." sv string "i"$0x0 vs .z.a
+"192.168.0.3"
+```
 
 ### Base-x representation