#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)
Service Program Name: QSOSRV2
Default Public Authority: *USE
Threadsafe: Yes
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
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.
res_send() calls res_init() if the _res
structure has not been initialized.
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.
res_send() does not perform interactive queries and expects the
name server to handle recursion.
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.
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.
In a thread-enabled environment, the _res structure is
shared among all threads within a process.