However the main use of this SWI is by the Acorn Internet module (2.10 or later) from the C language gethostbyname() function call. The exact algorithm followed is that on any hostname lookup, this SWI is called, and if no error is returned, then the hostent ptr returned is used by the Internet module. If an error is returned, the Internet module uses its own (broken) /etc/hosts file lookup code.

The hostent struct has the following, Net-BSD standard format - see <netdb.h> for more details;

  struct hostent
  {
    char    *h_name;               /* official name of host */
    char    **h_aliases;           /* alias list */
    int     h_addrtype;            /* host address type */
    int     h_length;              /* length of address */
    char    **h_addr_list;         /* list of addresses */
    #define h_addr h_addr_list[0]; /* address (compatiblity) */
  };

A Net-BSD standard 'errno' value is returned in R0 if there was an error. See <sys/errno.h> for details of error numbers.

To perform a host address-to-name reverse lookup, call this SWI with the host address converted to a string. eg, "127.0.0.1"

If there is a configuration error (such as Inet$Resolvers not being set), then a RISC OS error block pointer is returned in R0, and the V flag is set on exit.

If the hostname is a valid cache item, or present in the hosts file on disc, it is returned immediately in R1, with R0 set to 0.

If the hostname is a cache item, marked as failed, then R1 is set to NULL (0) and R0 is either -1 (host not found), or -2 (remote failure. eg, configured resolver didn't respond).

If the hostname is a cache item, marked as pending, then R1 is set to NULL (0) and R0 is EINPROGRESS (36 decimal). Items are marked as pending when a remote resolver lookup is in progress.
The calling program is expected to periodically call _GetHost until a valid hostent is returned, or an error condition occurs.

The calling program should run something like;

  EINPROGRESS = 36
  REPEAT
    SYS "Resolver_GetHost","www.ant.co.uk" TO status,hostent;
      flags
    error = flags AND 1
    REM Perhaps inform user of the state of this lookup
  UNTIL (error) OR (status <> EINPROGRESS)
  REM hostent is a valid pointer, or 0

Because name lookups can take anything up to 20 seconds or so, it is important to be able to give feedback to the user on the status of the lookup, as well as giving the foreground application time to perform other tasks.

To perform a host address-to-name reverse lookup, call this SWI with the host address converted to a string. eg, "127.0.0.1"

If there is a configuration error (such as Inet$Resolvers not being set), then a RISC OS error block pointer is returned in R0, and the V flag is set on exit.

Very old versions of the Resolver module used SWI 0x46001 for a host address to name lookup. For backwards compatibility with older applications, Resolver v0.49 and later still accepts this use of SWI 0x46001.