res_hostalias()--Retrieve Host Alias

Syntax

 #include <sys/types.h>
 #include <netinet/in.h>
 #include <arpa/nameser.h>
 #include <resolv.h>

 const char * res_hostalias(const state* res,
                            const char* name,
                            char* destination,
                            size_t destination_length)

  Service Program Name: QSOSRV2

  Default Public Authority: *USE

  Threadsafe: Yes

The res_hostalias() looks up the specified name in the host aliases file specified by the environment variable HOSTALIASES.

A user can create a host aliases file. This file maps user-defined aliases to host names, unlike the IBM^® i host table (or a DNS), which maps host names to IP addresses. Also, it requires no special authorities for a user to define an alias. It is simply a shorthand for a server which can be easily changed and controlled by users. No IBM i server default alias file is created.

The format is simply an alias followed by blank(s) followed by a domain name. For example, mypc may be an alias for m999.mydomain.ibm.com and myaix may be an alias for m111.mydomain.ibm.com:

mypc m999.mydomain.ibm.com.

myaix m111.mydomain.ibm.com

Other functions, like res_nsearch() or gethostbyname_r() will resolve an alias like "mypc" to the full domain name "m999.mydomain.ibm.com." before querying the DNS or IBM i host table.

Note:An alias may not contain periods.

Parameters

res: (Input) The pointer to the state structure.
name: (Input) The pointer to the host name.
destination: (Output) The pointer to the destination buffer. This pointer will be the return value if the call succeeds.
destination_length: (Input) The length of the destination buffer.

Authorities

Authorization of *R (allow access to the object) to the host aliases file specified by the HOSTALIASES environment variable.

You also need *X authority to each directory in the path of the host aliases file.

Return Value

(NULL) No alias found or an error occurred.

(destination) A pointer to the destination buffer updated with the alias found.

Error Conditions

When the res_hostalias() function fails, errno can be set to one of the following:

[EACCES]

Permission denied. The process does not have the appropriate privileges to the host aliases file specified by the HOSTALIASES environment variable.

[EFAULT]

The system detected a pointer that was invalid while attempting to access an input pointer.

[EINVAL]

One of the following reasons:

The res appears to have been previously initialized but the reserved field is not set to zeros or an input pointer was NULL.
An alias was found that contains a period.

Usage Notes

If the RES_NOALIASES option is set, no processing is done and a NULL will be returned.
If the res structure has not been initialized, res_ninit() will be called.

Related Information

res_findzonecut()--Find the Enclosing Zone and Servers
res_init()--Initialize res Structure
res_nclose()--Close Socket and Reset res Structure
res_nmkquery()--Place Domain Query in Buffer
res_nquery()--Send Domain Query
res_nsearch()--Search for Domain Name
res_nsend()--Send Buffered Domain Query
res_xlate()--Translate DNS Packets

API introduced: V5R1

[ Back to top | UNIX-Type APIs | APIs by category ]