res_hostalias()--Retrieve the host alias

 #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)  

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

A user may create a host aliases file. This file maps user defined aliases to host names, unlike the i5/OS 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's simply a shorthand for a server which can be easily changed and controlled by users. No iSeries 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 i5/OS 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

1. If the RES_NOALIASES option is set, no processing is done and a NULL will be returned.
   
   
2. 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