res_search()--Search for Domain Name

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

 int res_search(char *domain_name,
                int  class,
                int  type,
                char *answer_buffer,
                int  answer_buffer_length)

The res_search() function is used to make a query message and wait for a response.

Parameters

domain_name

(Input) The pointer to the domain name.

class

(Input) The class of data being looked for. See res_mkquery() or <arpa/nameser.h> for possible values.

type

(Input) The type of request being made. See res_mkquery() or <arpa/nameser.h> for possible values.

answer_buffer

(Output) The pointer to an address where the response is stored.

answer_buffer_length

(Input) The size of the answer area.

Return Value

res_search() returns an integer. Possible values are:

• -1 (unsuccessful)
  
  
• n (successful), where n is the actual size of the answer returned.

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.

Error Conditions

When the res_search() 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]

The _res appears to be initialized but the reserved field is not set to zeros.

When the res_search() function fails, h_errno (defined in <netdb.h>) can be set to one of the following:

[HOST_NOT_FOUND]

(Set by the call to res_query() ) The domain name specified by the domain_name parameter was not found. The return code in the response packet was NXDOMAIN.

[TRY_AGAIN]

Either the name server is not running or the name server returned SERVFAIL in the response packet.

[NO_RECOVERY]

(Set by the call to res_query() ) An unrecoverable error has occurred. Either the domain name could not be compressed because it was invalid or the name server returned FORMERR, NOTIMP, or REFUSED.

[NO_DATA]

(Set by the call to res_query() ) The domain name exists but there is no data of the requested type.

Usage Notes

1. The res_search() function implements the default and search rules controlled by the RES_DEFNAMES and RES_DNSRCH options. res_search() takes the domain name received in domain_name, and makes it fully qualified (if it is not already). res_search() also calls res_query(), passing it the different domain names to look up, until a successful response is received.
   
   
2. res_search() calls res_init() if the _res structure has not been initialized.
   
   
3. res_search() expects EBCDIC data as input. The output from res_search() is also EBCDIC.
   
   
4. In a thread-enabled environment, the _res structure is shared among all threads within a process.
   
   
5. res_search() will resolve local host aliases to a domain name which are then resolved with a query using DNS. See res_hostalias() for more information about aliases.
   
   

Related Information

• hstrerror()--Retrieve Resolver Error Message
  
  
• res_nsearch()--Search for Domain Name
  
  
• res_hostalias()--Retrieve the host alias
  
  
• res_init()--Initialize _res Structure
  
  
• res_mkquery()--Place Domain Query in Buffer
  
  
• res_query()--Send Domain Query
  
  
• res_close()--Close Socket and Reset _res Structure
  
  
• res_send()--Send Buffered Domain Query
  
  
• res_xlate()--Translate DNS Packets

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