Blame - ap/app/c-ares/src/ares_query.3 - T106_DC

blob: 733fbc972b58faa90c6d0385b45830a21b084064 [file] [log] [blame]

lh	9ed821d	2023-04-07 01:36:19 -0700	[diff] [blame^]	1	.\"
				2	.\" Copyright 1998 by the Massachusetts Institute of Technology.
				3	.\"
				4	.\" Permission to use, copy, modify, and distribute this
				5	.\" software and its documentation for any purpose and without
				6	.\" fee is hereby granted, provided that the above copyright
				7	.\" notice appear in all copies and that both that copyright
				8	.\" notice and this permission notice appear in supporting
				9	.\" documentation, and that the name of M.I.T. not be used in
				10	.\" advertising or publicity pertaining to distribution of the
				11	.\" software without specific, written prior permission.
				12	.\" M.I.T. makes no representations about the suitability of
				13	.\" this software for any purpose. It is provided "as is"
				14	.\" without express or implied warranty.
				15	.\"
				16	.TH ARES_QUERY 3 "24 July 1998"
				17	.SH NAME
				18	ares_query \- Initiate a single-question DNS query
				19	.SH SYNOPSIS
				20	.nf
				21	.B #include <ares.h>
				22	.PP
				23	.B typedef void (ares_callback)(void \fIarg\fP, int \fIstatus\fP,
				24	.B int \fItimeouts\fP, unsigned char *\fIabuf\fP, int \fIalen\fP)
				25	.PP
				26	.B void ares_query(ares_channel \fIchannel\fP, const char *\fIname\fP,
				27	.B int \fIdnsclass\fP, int \fItype\fP, ares_callback \fIcallback\fP,
				28	.B void *\fIarg\fP)
				29	.fi
				30	.SH DESCRIPTION
				31	The
				32	.B ares_query
				33	function initiates a single-question DNS query on the name service
				34	channel identified by
				35	.IR channel .
				36	The parameter
				37	.I name
				38	gives the query name as a NUL-terminated C string of period-separated
				39	labels optionally ending with a period; periods and backslashes within
				40	a label must be escaped with a backslash. The parameters
				41	.I dnsclass
				42	and
				43	.I type
				44	give the class and type of the query using the values defined in
				45	.BR <arpa/nameser.h> .
				46	When the query is complete or has failed, the ares library will invoke
				47	.IR callback .
				48	Completion or failure of the query may happen immediately, or may
				49	happen during a later call to
				50	.BR ares_process (3)
				51	or
				52	.BR ares_destroy (3).
				53	.PP
				54	The callback argument
				55	.I arg
				56	is copied from the
				57	.B ares_query
				58	argument
				59	.IR arg .
				60	The callback argument
				61	.I status
				62	indicates whether the query succeeded and, if not, how it failed. It
				63	may have any of the following values:
				64	.TP 19
				65	.B ARES_SUCCESS
				66	The query completed successfully.
				67	.TP 19
				68	.B ARES_ENODATA
				69	The query completed but contains no answers.
				70	.TP 19
				71	.B ARES_EFORMERR
				72	The query completed but the server claims that the query was
				73	malformatted.
				74	.TP 19
				75	.B ARES_ESERVFAIL
				76	The query completed but the server claims to have experienced a
				77	failure. (This code can only occur if the
				78	.B ARES_FLAG_NOCHECKRESP
				79	flag was specified at channel initialization time; otherwise, such
				80	responses are ignored at the
				81	.BR ares_send (3)
				82	level.)
				83	.TP 19
				84	.B ARES_ENOTFOUND
				85	The query completed but the queried-for domain name was not found.
				86	.TP 19
				87	.B ARES_ENOTIMP
				88	The query completed but the server does not implement the operation
				89	requested by the query. (This code can only occur if the
				90	.B ARES_FLAG_NOCHECKRESP
				91	flag was specified at channel initialization time; otherwise, such
				92	responses are ignored at the
				93	.BR ares_send (3)
				94	level.)
				95	.TP 19
				96	.B ARES_EREFUSED
				97	The query completed but the server refused the query. (This code can
				98	only occur if the
				99	.B ARES_FLAG_NOCHECKRESP
				100	flag was specified at channel initialization time; otherwise, such
				101	responses are ignored at the
				102	.BR ares_send (3)
				103	level.)
				104	.TP 19
				105	.B ARES_EBADNAME
				106	The query name
				107	.I name
				108	could not be encoded as a domain name, either because it contained a
				109	zero-length label or because it contained a label of more than 63
				110	characters.
				111	.TP 19
				112	.B ARES_ETIMEOUT
				113	No name servers responded within the timeout period.
				114	.TP 19
				115	.B ARES_ECONNREFUSED
				116	No name servers could be contacted.
				117	.TP 19
				118	.B ARES_ENOMEM
				119	Memory was exhausted.
				120	.TP 19
				121	.B ARES_ECANCELLED
				122	The query was cancelled.
				123	.TP 19
				124	.B ARES_EDESTRUCTION
				125	The name service channel
				126	.I channel
				127	is being destroyed; the query will not be completed.
				128	.PP
				129	The callback argument
				130	.I timeouts
				131	reports how many times a query timed out during the execution of the
				132	given request.
				133	.PP
				134	If the query completed (even if there was something wrong with it, as
				135	indicated by some of the above error codes), the callback argument
				136	.I abuf
				137	points to a result buffer of length
				138	.IR alen .
				139	If the query did not complete,
				140	.I abuf
				141	will be NULL and
				142	.I alen
				143	will be 0.
				144	.SH SEE ALSO
				145	.BR ares_process (3)
				146	.SH AUTHOR
				147	Greg Hudson, MIT Information Systems
				148	.br
				149	Copyright 1998 by the Massachusetts Institute of Technology.