.\" $OpenBSD: getrrsetbyname.3,v 1.4 2001/08/08 16:28:43 jakob Exp $
|
.\" $OpenBSD: getrrsetbyname.3,v 1.4 2001/08/08 16:28:43 jakob Exp $
|
.\"
|
.\"
|
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
.\"
|
.\"
|
.\" Permission to use, copy, modify, and distribute this software for any
|
.\" Permission to use, copy, modify, and distribute this software for any
|
.\" purpose with or without fee is hereby granted, provided that the above
|
.\" purpose with or without fee is hereby granted, provided that the above
|
.\" copyright notice and this permission notice appear in all copies.
|
.\" copyright notice and this permission notice appear in all copies.
|
.\"
|
.\"
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
.\"
|
.\"
|
.Dd Oct 18, 2000
|
.Dd Oct 18, 2000
|
.Dt GETRRSETBYNAME 3
|
.Dt GETRRSETBYNAME 3
|
.Os
|
.Os
|
.Sh NAME
|
.Sh NAME
|
.Nm getrrsetbyname
|
.Nm getrrsetbyname
|
.Nd retrieve DNS records
|
.Nd retrieve DNS records
|
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
.Fd #include
|
.Fd #include
|
.Ft int
|
.Ft int
|
.Fn getrrsetbyname "const char *hostname" "unsigned int rdclass" \
|
.Fn getrrsetbyname "const char *hostname" "unsigned int rdclass" \
|
"unsigned int rdtype" "unsigned int flags" "struct rrsetinfo **res"
|
"unsigned int rdtype" "unsigned int flags" "struct rrsetinfo **res"
|
.Ft int
|
.Ft int
|
.Fn freerrset "struct rrsetinfo **rrset"
|
.Fn freerrset "struct rrsetinfo **rrset"
|
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
.Fn getrrsetbyname
|
.Fn getrrsetbyname
|
gets a set of resource records associated with a
|
gets a set of resource records associated with a
|
.Fa hostname ,
|
.Fa hostname ,
|
.Fa class
|
.Fa class
|
and
|
and
|
.Fa type .
|
.Fa type .
|
.Fa hostname
|
.Fa hostname
|
is a pointer a to null-terminated string.
|
is a pointer a to null-terminated string.
|
The
|
The
|
.Fa flags
|
.Fa flags
|
field is currently unused and must be zero.
|
field is currently unused and must be zero.
|
.Pp
|
.Pp
|
After a successful call to
|
After a successful call to
|
.Fn getrrsetbyname ,
|
.Fn getrrsetbyname ,
|
.Fa *res
|
.Fa *res
|
is a pointer to an
|
is a pointer to an
|
.Li rrsetinfo
|
.Li rrsetinfo
|
structure, containing a list of one or more
|
structure, containing a list of one or more
|
.Li rdatainfo
|
.Li rdatainfo
|
structures containing resource records and potentially another list of
|
structures containing resource records and potentially another list of
|
.Li rdatainfo
|
.Li rdatainfo
|
structures containing SIG resource records associated with those records.
|
structures containing SIG resource records associated with those records.
|
The members
|
The members
|
.Li rri_rdclass
|
.Li rri_rdclass
|
and
|
and
|
.Li rri_rdtype
|
.Li rri_rdtype
|
are copied from the parameters.
|
are copied from the parameters.
|
.Li rri_ttl
|
.Li rri_ttl
|
and
|
and
|
.Li rri_name
|
.Li rri_name
|
are properties of the obtained rrset.
|
are properties of the obtained rrset.
|
The resource records contained in
|
The resource records contained in
|
.Li rri_rdatas
|
.Li rri_rdatas
|
and
|
and
|
.Li rri_sigs
|
.Li rri_sigs
|
are in uncompressed DNS wire format.
|
are in uncompressed DNS wire format.
|
Properties of the rdataset are represented in the
|
Properties of the rdataset are represented in the
|
.Li rri_flags
|
.Li rri_flags
|
bitfield. If the
|
bitfield. If the
|
.Dv RRSET_VALIDATED
|
.Dv RRSET_VALIDATED
|
bit is set, the data has been DNSSEC
|
bit is set, the data has been DNSSEC
|
validated and the signatures verified.
|
validated and the signatures verified.
|
.Pp
|
.Pp
|
The following structures are used:
|
The following structures are used:
|
.Bd -literal -offset
|
.Bd -literal -offset
|
struct rdatainfo {
|
struct rdatainfo {
|
unsigned int rdi_length; /* length of data */
|
unsigned int rdi_length; /* length of data */
|
unsigned char *rdi_data; /* record data */
|
unsigned char *rdi_data; /* record data */
|
};
|
};
|
|
|
struct rrsetinfo {
|
struct rrsetinfo {
|
unsigned int rri_flags; /* RRSET_VALIDATED ... */
|
unsigned int rri_flags; /* RRSET_VALIDATED ... */
|
unsigned int rri_rdclass; /* class number */
|
unsigned int rri_rdclass; /* class number */
|
unsigned int rri_rdtype; /* RR type number */
|
unsigned int rri_rdtype; /* RR type number */
|
unsigned int rri_ttl; /* time to live */
|
unsigned int rri_ttl; /* time to live */
|
unsigned int rri_nrdatas; /* size of rdatas array */
|
unsigned int rri_nrdatas; /* size of rdatas array */
|
unsigned int rri_nsigs; /* size of sigs array */
|
unsigned int rri_nsigs; /* size of sigs array */
|
char *rri_name; /* canonical name */
|
char *rri_name; /* canonical name */
|
struct rdatainfo *rri_rdatas; /* individual records */
|
struct rdatainfo *rri_rdatas; /* individual records */
|
struct rdatainfo *rri_sigs; /* individual signatures */
|
struct rdatainfo *rri_sigs; /* individual signatures */
|
};
|
};
|
.Ed
|
.Ed
|
.Pp
|
.Pp
|
All of the information returned by
|
All of the information returned by
|
.Fn getrrsetbyname
|
.Fn getrrsetbyname
|
is dynamically allocated: the
|
is dynamically allocated: the
|
.Li rrsetinfo
|
.Li rrsetinfo
|
and
|
and
|
.Li rdatainfo
|
.Li rdatainfo
|
structures,
|
structures,
|
and the canonical host name strings pointed to by the
|
and the canonical host name strings pointed to by the
|
.Li rrsetinfostructure.
|
.Li rrsetinfostructure.
|
Memory allocated for the dynamically allocated structures created by
|
Memory allocated for the dynamically allocated structures created by
|
a successful call to
|
a successful call to
|
.Fn getrrsetbyname
|
.Fn getrrsetbyname
|
is released by
|
is released by
|
.Fn freerrset .
|
.Fn freerrset .
|
.Li rrset
|
.Li rrset
|
is a pointer to a
|
is a pointer to a
|
.Li struct rrset
|
.Li struct rrset
|
created by a call to
|
created by a call to
|
.Fn getrrsetbyname .
|
.Fn getrrsetbyname .
|
.Pp
|
.Pp
|
If the EDNS0 option is activated in
|
If the EDNS0 option is activated in
|
.Xr resolv.conf 3 ,
|
.Xr resolv.conf 3 ,
|
.Fn getrrsetbyname
|
.Fn getrrsetbyname
|
will request DNSSEC authentication using the EDNS0 DNSSEC OK (DO) bit.
|
will request DNSSEC authentication using the EDNS0 DNSSEC OK (DO) bit.
|
.Sh "RETURN VALUES"
|
.Sh "RETURN VALUES"
|
.Fn getrrsetbyname
|
.Fn getrrsetbyname
|
returns zero on success, and one of the following error
|
returns zero on success, and one of the following error
|
codes if an error occurred:
|
codes if an error occurred:
|
.Pp
|
.Pp
|
.Bl -tag -width ERRSET_NOMEMORY -compact
|
.Bl -tag -width ERRSET_NOMEMORY -compact
|
.It Dv ERRSET_NONAME
|
.It Dv ERRSET_NONAME
|
the name does not exist
|
the name does not exist
|
.It Dv ERRSET_NODATA
|
.It Dv ERRSET_NODATA
|
the name exists, but does not have data of the desired type
|
the name exists, but does not have data of the desired type
|
.It Dv ERRSET_NOMEMORY
|
.It Dv ERRSET_NOMEMORY
|
memory could not be allocated
|
memory could not be allocated
|
.It Dv ERRSET_INVAL
|
.It Dv ERRSET_INVAL
|
a parameter is invalid
|
a parameter is invalid
|
.It Dv ERRSET_FAIL
|
.It Dv ERRSET_FAIL
|
other failure
|
other failure
|
.El
|
.El
|
.Sh SEE ALSO
|
.Sh SEE ALSO
|
.Xr resolver 3 ,
|
.Xr resolver 3 ,
|
.Xr resolv.conf 5 ,
|
.Xr resolv.conf 5 ,
|
.Xr named 8
|
.Xr named 8
|
.Sh AUTHORS
|
.Sh AUTHORS
|
Jakob Schlyter
|
Jakob Schlyter
|
.Aq jakob@openbsd.org
|
.Aq jakob@openbsd.org
|
.Sh HISTORY
|
.Sh HISTORY
|
.Fn getrrsetbyname
|
.Fn getrrsetbyname
|
first appeared in
|
first appeared in
|
.Ox 3.0 .
|
.Ox 3.0 .
|
The API first appeared in ISC BIND version 9.
|
The API first appeared in ISC BIND version 9.
|
.Sh BUGS
|
.Sh BUGS
|
The data in
|
The data in
|
.Li *rdi_data
|
.Li *rdi_data
|
should be returned in uncompressed wire format.
|
should be returned in uncompressed wire format.
|
Currently, the data is in compressed format and the caller can't
|
Currently, the data is in compressed format and the caller can't
|
uncompress since it doesn't have the full message.
|
uncompress since it doesn't have the full message.
|
.Sh CAVEATS
|
.Sh CAVEATS
|
The
|
The
|
.Dv RRSET_VALIDATED
|
.Dv RRSET_VALIDATED
|
flag in
|
flag in
|
.Li rri_flags
|
.Li rri_flags
|
is set if the AD (autenticated data) bit in the DNS answer is
|
is set if the AD (autenticated data) bit in the DNS answer is
|
set. This flag
|
set. This flag
|
.Em should not
|
.Em should not
|
be trusted unless the transport between the nameserver and the resolver
|
be trusted unless the transport between the nameserver and the resolver
|
is secure (e.g. IPsec, trusted network, loopback communication).
|
is secure (e.g. IPsec, trusted network, loopback communication).
|
|
|
