← Back to branch summary

~andreserl/ubuntu/lucid/bind9/bind9-apport-533601

« back to all changes in this revision

Viewing changes to lib/lwres/man/lwres_gabn.3

  • Committer: Bazaar Package Importer
  • Author(s): LaMont Jones
  • Date: 2006-01-05 12:29:28 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20060105122928-oih7ttkkmpb90q8q
Tags: 1:9.3.2-1
* New upstream
* use lsb-base for start/stop messages in init.d.
* switch to debhelper 4

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/lwres/man/lwres_gabn.3
1
 
.\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
2
 
.\" Copyright (C) 2000, 2001  Internet Software Consortium.
3
 
.\"
 
1
.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
 
2
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
 
3
.\" 
4
4
.\" Permission to use, copy, modify, and distribute this software for any
5
5
.\" purpose with or without fee is hereby granted, provided that the above
6
6
.\" copyright notice and this permission notice appear in all copies.
7
 
.\"
 
7
.\" 
8
8
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9
9
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10
 
.\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 
10
.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
11
11
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12
12
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
13
13
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14
14
.\" PERFORMANCE OF THIS SOFTWARE.
15
15
.\"
16
 
.\" $Id: lwres_gabn.3,v 1.13.2.1.8.1 2004/03/06 07:41:42 marka Exp $
 
16
.\" $Id: lwres_gabn.3,v 1.13.2.1.8.5 2005/10/13 02:33:52 marka Exp $
17
17
.\"
18
 
.TH "LWRES_GABN" "3" "Jun 30, 2000" "BIND9" ""
19
 
.SH NAME
 
18
.hy 0
 
19
.ad l
 
20
.\" ** You probably do not want to edit this file directly **
 
21
.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
 
22
.\" Instead of manually editing it, you probably should edit the DocBook XML
 
23
.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
 
24
.TH "LWRES_GABN" "3" "Jun 30, 2000" "BIND9" "BIND9"
 
25
.\" disable hyphenation
 
26
.nh
 
27
.\" disable justification (adjust text to left margin only)
 
28
.ad l
 
29
.SH "NAME"
20
30
lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free \- lightweight resolver getaddrbyname message handling
21
 
.SH SYNOPSIS
22
 
\fB#include <lwres/lwres.h>
23
 
.sp
24
 
.na
25
 
lwres_result_t
26
 
lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);
27
 
.ad
28
 
.sp
29
 
.na
30
 
lwres_result_t
31
 
lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);
32
 
.ad
33
 
.sp
34
 
.na
35
 
lwres_result_t
36
 
lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);
37
 
.ad
38
 
.sp
39
 
.na
40
 
lwres_result_t
41
 
lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp);
42
 
.ad
43
 
.sp
44
 
.na
45
 
void
46
 
lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp);
47
 
.ad
48
 
.sp
49
 
.na
50
 
void
51
 
lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp);
52
 
.ad
53
 
\fR
 
31
.SH "SYNOPSIS"
 
32
.nf
 
33
#include <lwres/lwres.h>
 
34
.fi
 
35
.HP 40
 
36
\fBlwres_result_t\ \fBlwres_gabnrequest_render\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_gabnrequest_t\ *req\fR\fB, \fR\fBlwres_lwpacket_t\ *pkt\fR\fB, \fR\fBlwres_buffer_t\ *b\fR\fB);\fR
 
37
.HP 41
 
38
\fBlwres_result_t\ \fBlwres_gabnresponse_render\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_gabnresponse_t\ *req\fR\fB, \fR\fBlwres_lwpacket_t\ *pkt\fR\fB, \fR\fBlwres_buffer_t\ *b\fR\fB);\fR
 
39
.HP 39
 
40
\fBlwres_result_t\ \fBlwres_gabnrequest_parse\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_buffer_t\ *b\fR\fB, \fR\fBlwres_lwpacket_t\ *pkt\fR\fB, \fR\fBlwres_gabnrequest_t\ **structp\fR\fB);\fR
 
41
.HP 40
 
42
\fBlwres_result_t\ \fBlwres_gabnresponse_parse\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_buffer_t\ *b\fR\fB, \fR\fBlwres_lwpacket_t\ *pkt\fR\fB, \fR\fBlwres_gabnresponse_t\ **structp\fR\fB);\fR
 
43
.HP 29
 
44
\fBvoid\ \fBlwres_gabnresponse_free\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_gabnresponse_t\ **structp\fR\fB);\fR
 
45
.HP 28
 
46
\fBvoid\ \fBlwres_gabnrequest_free\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_gabnrequest_t\ **structp\fR\fB);\fR
54
47
.SH "DESCRIPTION"
55
48
.PP
56
 
These are low-level routines for creating and parsing
57
 
lightweight resolver name-to-address lookup request and 
58
 
response messages.
 
49
These are low\-level routines for creating and parsing lightweight resolver name\-to\-address lookup request and response messages.
59
50
.PP
60
 
There are four main functions for the getaddrbyname opcode.
61
 
One render function converts a getaddrbyname request structure \(em
62
 
\fBlwres_gabnrequest_t\fR \(em
63
 
to the lighweight resolver's canonical format.
64
 
It is complemented by a parse function that converts a packet in this
65
 
canonical format to a getaddrbyname request structure.
66
 
Another render function converts the getaddrbyname response structure \(em
67
 
\fBlwres_gabnresponse_t\fR \(em
68
 
to the canonical format.
69
 
This is complemented by a parse function which converts a packet in
70
 
canonical format to a getaddrbyname response structure.
 
51
There are four main functions for the getaddrbyname opcode. One render function converts a getaddrbyname request structure \(em
 
52
\fBlwres_gabnrequest_t\fR
 
53
\(em to the lighweight resolver's canonical format. It is complemented by a parse function that converts a packet in this canonical format to a getaddrbyname request structure. Another render function converts the getaddrbyname response structure \(em
 
54
\fBlwres_gabnresponse_t\fR
 
55
\(em to the canonical format. This is complemented by a parse function which converts a packet in canonical format to a getaddrbyname response structure.
71
56
.PP
72
57
These structures are defined in
73
 
\fI<lwres/lwres.h>\fR.
74
 
They are shown below.
 
58
\fI<lwres/lwres.h>\fR. They are shown below.
75
59
.sp
76
60
.nf
77
61
#define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
78
 
 
79
62
typedef struct lwres_addr lwres_addr_t;
80
63
typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
81
 
 
82
64
typedef struct {
83
65
        lwres_uint32_t  flags;
84
66
        lwres_uint32_t  addrtypes;
85
67
        lwres_uint16_t  namelen;
86
68
        char           *name;
87
69
} lwres_gabnrequest_t;
88
 
 
89
70
typedef struct {
90
71
        lwres_uint32_t          flags;
91
72
        lwres_uint16_t          naliases;
98
79
        void                   *base;
99
80
        size_t                  baselen;
100
81
} lwres_gabnresponse_t;
 
82
.fi
101
83
.sp
102
 
.fi
103
84
.PP
104
85
\fBlwres_gabnrequest_render()\fR
105
86
uses resolver context
106
87
\fIctx\fR
107
88
to convert getaddrbyname request structure
108
89
\fIreq\fR
109
 
to canonical format.
110
 
The packet header structure
 
90
to canonical format. The packet header structure
111
91
\fIpkt\fR
112
 
is initialised and transferred to
113
 
buffer
114
 
\fIb\fR.
115
 
The contents of
 
92
is initialised and transferred to buffer
 
93
\fIb\fR. The contents of
116
94
\fI*req\fR
117
95
are then appended to the buffer in canonical format.
118
96
\fBlwres_gabnresponse_render()\fR
127
105
\fIpkt\fR
128
106
to a
129
107
\fBlwres_gabnrequest_t\fR
130
 
structure.
131
 
Buffer
 
108
structure. Buffer
132
109
\fIb\fR
133
 
provides space to be used for storing this structure.
134
 
When the function succeeds, the resulting
 
110
provides space to be used for storing this structure. When the function succeeds, the resulting
135
111
\fBlwres_gabnrequest_t\fR
136
112
is made available through
137
113
\fI*structp\fR.
152
128
or
153
129
\fBlwres_gabnrequest_t\fR
154
130
structures referenced via
155
 
\fIstructp\fR.
156
 
Any memory associated with ancillary buffers and strings for those
157
 
structures is also discarded.
 
131
\fIstructp\fR. Any memory associated with ancillary buffers and strings for those structures is also discarded.
158
132
.SH "RETURN VALUES"
159
133
.PP
160
134
The getaddrbyname opcode functions
161
 
\fBlwres_gabnrequest_render()\fR, 
162
 
\fBlwres_gabnresponse_render()\fR
163
 
\fBlwres_gabnrequest_parse()\fR
 
135
\fBlwres_gabnrequest_render()\fR,
 
136
\fBlwres_gabnresponse_render()\fR\fBlwres_gabnrequest_parse()\fR
164
137
and
165
138
\fBlwres_gabnresponse_parse()\fR
166
139
all return
167
 
LWRES_R_SUCCESS
168
 
on success.
169
 
They return
170
 
LWRES_R_NOMEMORY
 
140
\fBLWRES_R_SUCCESS\fR
 
141
on success. They return
 
142
\fBLWRES_R_NOMEMORY\fR
171
143
if memory allocation fails.
172
 
LWRES_R_UNEXPECTEDEND
 
144
\fBLWRES_R_UNEXPECTEDEND\fR
173
145
is returned if the available space in the buffer
174
146
\fIb\fR
175
147
is too small to accommodate the packet header or the
181
153
and
182
154
\fBlwres_gabnresponse_parse()\fR
183
155
will return
184
 
LWRES_R_UNEXPECTEDEND
185
 
if the buffer is not empty after decoding the received packet.
186
 
These functions will return
187
 
LWRES_R_FAILURE
 
156
\fBLWRES_R_UNEXPECTEDEND\fR
 
157
if the buffer is not empty after decoding the received packet. These functions will return
 
158
\fBLWRES_R_FAILURE\fR
188
159
if
189
 
\fBpktflags\fR
 
160
pktflags
190
161
in the packet header structure
191
162
\fBlwres_lwpacket_t\fR
192
163
indicate that the packet is not a response to an earlier query.
193
164
.SH "SEE ALSO"
194
165
.PP
195
 
\fBlwres_packet\fR(3)
 
166
\fBlwres_packet\fR(3 )