From 4d833ef73b218a255c54ba095ff1feaaf4177d21 Mon Sep 17 00:00:00 2001 From: Brian Wellington Date: Thu, 2 Nov 2000 02:21:09 +0000 Subject: [PATCH] Document lwres_getrrsetbyname --- doc/man/lwres/lwres_getrrsetbyname.3 | 115 +++++++++++++++++++++++++++ lib/lwres/man/lwres_getrrsetbyname.3 | 115 +++++++++++++++++++++++++++ 2 files changed, 230 insertions(+) create mode 100644 doc/man/lwres/lwres_getrrsetbyname.3 create mode 100644 lib/lwres/man/lwres_getrrsetbyname.3 diff --git a/doc/man/lwres/lwres_getrrsetbyname.3 b/doc/man/lwres/lwres_getrrsetbyname.3 new file mode 100644 index 0000000000..d93ac689ad --- /dev/null +++ b/doc/man/lwres/lwres_getrrsetbyname.3 @@ -0,0 +1,115 @@ +.Dd Oct 18, 2000 +.Dt LWRES_GETRRSETBYNAME 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_getrrsetbyname , +.Nm lwres_freerrset +.Nd retrieve dns records +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft int +.Fo lwres_getrrsetbyname +.Fa "const char *hostname" +.Fa "unsigned int rdclass" +.Fa "unsigned int rdtype" +.Fa "unsigned int flags" +.Fa "struct rrsetinfo **res" +.Fc +.Ft void +.Fo lwres_freerrset +.Fa "struct rrsetinfo *rrset" +.Fc +.Pp +The following structures are used: +.Pp +.Bd -literal -offset indent +struct rdatainfo { + unsigned int rdi_length; /* length of data */ + unsigned char *rdi_data; /* record data */ +}; + +struct rrsetinfo { + unsigned int rri_flags; /* none defined */ + unsigned int rri_rdclass; /* need constants... */ + unsigned int rri_rdtype; /* need constants... */ + unsigned int rri_ttl; /* time to live */ + unsigned int rri_nrdatas; /* size of rdatas array */ + unsigned int rri_nsigs; /* size of sigs array */ + char *rri_name; /* canonical name */ + struct rdatainfo *rri_rdatas; /* individual records */ + struct rdatainfo *rri_sigs; /* individual signatures */ +}; +.Ed +.Sh DESCRIPTION +.Pp +.Fn lwres_getrrsetbyname +is used to get a set of resource records associated with a +.Fa hostname , +.Fa class , +and +.Fa type . +.Fa hostname +is +a pointer a to null-terminated string. The +.Fa flags +field is currently unused. +.Pp +After a successful call to +.Fn lwres_getrrsetbyname , +.Fa *res +is a pointer to an +.Dv rrsetinfo +structure, containing a list of one or more +.Dv rdatainfo +structures containing resource records and potentially another list of +.Dv rdatainfo +structures containing signatures. +The members +.Li rri_rdclass +and +.Li rri_rdtype +are copied from the parameters. +.Li rri_ttl +and +.Li rri_name +are properties of the obtained rrset. +The resource records contained in +.Li rri_rdatas +and +.Li rri_sigs +are in uncompressed DNS wire format. +Properties of the rdataset are represented in the +.Li rri_flags +bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC +validated and the signatures verified. If the RRSET_AUTHORITATIVE bit +is set, the queried ligghtweight resolver server was authoritative for the +data. +.Pp +All of the information returned by +.Fn lwres_getrrsetbyname +is dynamically allocated: the +.Li rrsetinfo +and +.Li rdatainfo +structures, +and the canonical host name strings pointed to by the +.Li rrsetinfo structure. +Memory allocated for the dynamically allocated structures created by +a successful call to +.Fn lwres_getrrsetbyname +is released by +.Fn lwres_freerrset . +.Fa rrset +is a pointer to a +.Dv "struct rrset" +created by a call to +.Fn lwres_getrrsetbyname . +.Sh RETURN VALUES +.Fn lwres_getrrsetbyname +returns zero on success or an error code if an error occurs. The defined +error codes are ERRSET_NOMEMORY (memory could not be allocated), +ERRSET_INVAL (a parameter is invalid) and ERRSET_FAIL (other failure). +.Sh SEE ALSO +.Xr lwres 3 . diff --git a/lib/lwres/man/lwres_getrrsetbyname.3 b/lib/lwres/man/lwres_getrrsetbyname.3 new file mode 100644 index 0000000000..d93ac689ad --- /dev/null +++ b/lib/lwres/man/lwres_getrrsetbyname.3 @@ -0,0 +1,115 @@ +.Dd Oct 18, 2000 +.Dt LWRES_GETRRSETBYNAME 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_getrrsetbyname , +.Nm lwres_freerrset +.Nd retrieve dns records +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft int +.Fo lwres_getrrsetbyname +.Fa "const char *hostname" +.Fa "unsigned int rdclass" +.Fa "unsigned int rdtype" +.Fa "unsigned int flags" +.Fa "struct rrsetinfo **res" +.Fc +.Ft void +.Fo lwres_freerrset +.Fa "struct rrsetinfo *rrset" +.Fc +.Pp +The following structures are used: +.Pp +.Bd -literal -offset indent +struct rdatainfo { + unsigned int rdi_length; /* length of data */ + unsigned char *rdi_data; /* record data */ +}; + +struct rrsetinfo { + unsigned int rri_flags; /* none defined */ + unsigned int rri_rdclass; /* need constants... */ + unsigned int rri_rdtype; /* need constants... */ + unsigned int rri_ttl; /* time to live */ + unsigned int rri_nrdatas; /* size of rdatas array */ + unsigned int rri_nsigs; /* size of sigs array */ + char *rri_name; /* canonical name */ + struct rdatainfo *rri_rdatas; /* individual records */ + struct rdatainfo *rri_sigs; /* individual signatures */ +}; +.Ed +.Sh DESCRIPTION +.Pp +.Fn lwres_getrrsetbyname +is used to get a set of resource records associated with a +.Fa hostname , +.Fa class , +and +.Fa type . +.Fa hostname +is +a pointer a to null-terminated string. The +.Fa flags +field is currently unused. +.Pp +After a successful call to +.Fn lwres_getrrsetbyname , +.Fa *res +is a pointer to an +.Dv rrsetinfo +structure, containing a list of one or more +.Dv rdatainfo +structures containing resource records and potentially another list of +.Dv rdatainfo +structures containing signatures. +The members +.Li rri_rdclass +and +.Li rri_rdtype +are copied from the parameters. +.Li rri_ttl +and +.Li rri_name +are properties of the obtained rrset. +The resource records contained in +.Li rri_rdatas +and +.Li rri_sigs +are in uncompressed DNS wire format. +Properties of the rdataset are represented in the +.Li rri_flags +bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC +validated and the signatures verified. If the RRSET_AUTHORITATIVE bit +is set, the queried ligghtweight resolver server was authoritative for the +data. +.Pp +All of the information returned by +.Fn lwres_getrrsetbyname +is dynamically allocated: the +.Li rrsetinfo +and +.Li rdatainfo +structures, +and the canonical host name strings pointed to by the +.Li rrsetinfo structure. +Memory allocated for the dynamically allocated structures created by +a successful call to +.Fn lwres_getrrsetbyname +is released by +.Fn lwres_freerrset . +.Fa rrset +is a pointer to a +.Dv "struct rrset" +created by a call to +.Fn lwres_getrrsetbyname . +.Sh RETURN VALUES +.Fn lwres_getrrsetbyname +returns zero on success or an error code if an error occurs. The defined +error codes are ERRSET_NOMEMORY (memory could not be allocated), +ERRSET_INVAL (a parameter is invalid) and ERRSET_FAIL (other failure). +.Sh SEE ALSO +.Xr lwres 3 .