res_send()--Send Buffered Domain Query or Update

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

 int res_send(char *query_buffer,
              int  query_buffer_length,
              char *answer_buffer,
              int  answer_buffer_length)

The res_send() function is used to send a query or update message to a name server and retrieve a response.

Parameters

query_buffer

(Input) The pointer to the query or update message.

query_buffer_length

(Input) The length of query_buffer.

answer_buffer

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

answer_buffer_length

(Input) The size of the answer_buffer.

Authorities:

No authorization is required.

Return Value

res_send() returns an integer. Possible values are:

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

Error Conditions

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

[ECONNREFUSED]

Not able to connect to a server.

[ECONVERT]

Either the input packet could not be translated to ASCII or the answer received could not be translated to the coded character set identifier (CCSID) currently in effect for the job.

[EINVAL]

One of the following reasons:

An invalid length or NULL pointer was passed to res_send() or The _res could not be initialized properly or The _res appears to be initialized but the reserved field is not set to zeros.

Note: No attempt is made to initialize the _res structure if it was initialized previous to the res_send() being issued.

[ESRCH]

No DNS servers were specified in nsaddr.

[ETIMEDOUT]

A timeout received from a connected server.

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

HOST_NOT_FOUND

Either the input packet could not be translated to ASCII or the answer received could not be translated to the coded character set identifier (CCSID) currently in effect for the job.

NO_RECOVERY

An invalid length or NULL pointer was passed to res_send() or the _res could not be initialized properly.

Notes:

• No attempt is made to initialize the _res structure if it was initialized previous to the res_send() being issued.
  
  
• There are numerous other values that errno can be set to by the sockets functions that res_send() calls. The above values are the only values that res_send() can specifically set. Refer to other sockets functions for the other values. errno is always set in an error condition, but h_errno is not necessarily set.

After receiving an error reply packet, res_send() will set the extended_error field in the state structure to the last reply return code from the DNS server. See <arpa/nameser.h> for all possible values of ns_rcode.

Usage Notes

1. res_send() sends the query or update to the local name server and handles all timeouts and retries. The response packet is stored in answer_buffer.
   
   
2. res_send() calls res_init() if the _res structure has not been initialized.
   
   
3. res_send() uses the UDP protocol, except for the following cases in which it uses TCP to send the packet.
   • If the RES_USEVC or RES_STAYOPEN bits are set in the options field of the _res structure.
     
     
   • If the configuration from Change TCP/IP Domain (CHGTCPDMN) specifies that the server protocol is TCP.
     
     
   • If the truncation bit is set in the packet header on the response from a UDP packet, and RES_IGNTC is not set in the _res structure.
   
   
4. res_send() does not perform interactive queries and expects the name server to handle recursion.
   
   
5. res_send() assumes that the data passed to it is EBCDIC and is in the default coded character set identifier (CCSID) currently in effect for the job. It translates the data from the default CCSID currently in effect for the job to ASCII (CCSID 819) before the data is sent out to a name server. The response that it receives from the name server is returned in the default CCSID currently in effect for the job.
   
   
6. Unless RES_NOCACHE was specified, res_send() checks the cached data for the answer to the query (but not for updates). If the answer is found and the time to live has not expired, it is returned to the calling program in answer_buffer and no attempt is made to send it on the network. If the time to live has expired, the entry is deleted from the cache, and the query is sent on the network. If the answer is not found in the cache, res_send() also sends the query on the network. When an answer is received from the network, it is placed in cache if it is an authoritative answer and is not the result of an inverse query. RES_NOCACHE does not stop answers from being cached. Authoritative negative replies, indicating the data does not exist, will also be cached.
   
   
7. In a thread-enabled environment, the _res structure is shared among all threads within a process.

Related Information

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