Debian Codegraph @

deps/libneon/doc/man/ne_addr_resolve.3

raw
1 '\" t
2 .\" Title: ne_addr_resolve
3 .\" Author:
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\" Date: 3 May 2011
6 .\" Manual: neon API reference
7 .\" Source: neon 0.29.6
8 .\" Language: English
9 .\"
10 .TH "NE_ADDR_RESOLVE" "3" "3 May 2011" "neon 0.29.6" "neon API reference"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 ne_addr_resolve, ne_addr_result, ne_addr_first, ne_addr_next, ne_addr_error, ne_addr_destroy \- functions to resolve hostnames to addresses
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <ne_socket\&.h>
37 .fi
38 .ft
39 .HP \w'ne_sock_addr\ *ne_addr_resolve('u
40 .BI "ne_sock_addr *ne_addr_resolve(const\ char\ *" "hostname" ", int\ " "flags" ");"
41 .HP \w'int\ ne_addr_result('u
42 .BI "int ne_addr_result(const\ ne_sock_addr\ *" "addr" ");"
43 .HP \w'const\ ne_inet_addr\ *ne_addr_first('u
44 .BI "const ne_inet_addr *ne_addr_first(ne_sock_addr\ *" "addr" ");"
45 .HP \w'const\ ne_inet_addr\ *ne_addr_next('u
46 .BI "const ne_inet_addr *ne_addr_next(ne_sock_addr\ *" "addr" ");"
47 .HP \w'char\ *ne_addr_error('u
48 .BI "char *ne_addr_error(const\ ne_sock_addr\ *" "addr" ", char\ *" "buffer" ", size_t\ " "bufsiz" ");"
49 .HP \w'void\ ne_addr_destroy('u
50 .BI "void ne_addr_destroy(ne_sock_addr\ *" "addr" ");"
51 .SH "DESCRIPTION"
52 .PP
53 The
54 \fBne_addr_resolve\fR
55 function resolves the given
56 \fIhostname\fR, returning an
57 \fBne_sock_addr\fR
58 object representing the address (or addresses) associated with the hostname\&. The
59 \fIflags\fR
60 parameter is currently unused, and must be passed as 0\&.
61 .PP
62 The
63 \fIhostname\fR
64 passed to
65 \fBne_addr_resolve\fR
66 can be a DNS hostname (e\&.g\&.
67 "www\&.example\&.com") or an IPv4 dotted quad (e\&.g\&.
68 "192\&.0\&.34\&.72"); or, on systems which support IPv6, an IPv6 hex address, which may be enclosed in brackets, e\&.g\&.
69 "[::1]"\&.
70 .PP
71 To determine whether the hostname was successfully resolved, the
72 \fBne_addr_result\fR
73 function is used, which returns non\-zero if an error occurred\&. If an error did occur, the
74 \fBne_addr_error\fR
75 function can be used, which will copy the error string into a given
76 \fIbuffer\fR
77 (of size
78 \fIbufsiz\fR)\&.
79 .PP
80 The functions
81 \fBne_addr_first\fR
82 and
83 \fBne_addr_next\fR
84 are used to retrieve the Internet addresses associated with an address object which has been successfully resolved\&.
85 \fBne_addr_first\fR
86 returns the first address;
87 \fBne_addr_next\fR
88 returns the next address after the most recent call to
89 \fBne_addr_next\fR
90 or
91 \fBne_addr_first\fR, or
92 NULL
93 if there are no more addresses\&. The
94 \fBne_inet_addr\fR
95 pointer returned by these functions can be passed to
96 \fBne_sock_connect\fR
97 to connect a socket\&.
98 .PP
99 After the address object has been used, it should be destroyed using
100 \fBne_addr_destroy\fR\&.
101 .SH "RETURN VALUE"
102 .PP
103 \fBne_addr_resolve\fR
104 returns a pointer to an address object, and never
105 NULL\&.
106 \fBne_addr_error\fR
107 returns the
108 \fIbuffer\fR
109 parameter \&.
110 .SH "EXAMPLES"
111 .PP
112 The code below prints out the set of addresses associated with the hostname
113 www\&.google\&.com\&.
114 .sp
115 .if n \{\
116 .RS 4
117 .\}
118 .nf
119 ne_sock_addr *addr;
120 char buf[256];
121
122 addr = ne_addr_resolve("www\&.google\&.com", 0);
123 if (ne_addr_result(addr)) {
124 printf("Could not resolve www\&.google\&.com: %s\en",
125 ne_addr_error(addr, buf, sizeof buf));
126 } else {
127 const ne_inet_addr *ia;
128 printf("www\&.google\&.com:");
129 for (ia = ne_addr_first(addr); ia != NULL; ia = ne_addr_next(addr)) {
130 printf(" %s", ne_iaddr_print(ia, buf, sizeof buf));
131 }
132 putchar(\*(Aq\en\*(Aq);
133 }
134 ne_addr_destroy(addr);
135 .fi
136 .if n \{\
137 .RE
138 .\}
139 .SH "SEE ALSO"
140 .PP
141 ne_iaddr_print
142 .SH "AUTHOR"
143 .PP
144 \fBJoe Orton\fR <\&[email protected]\&>
145 .RS 4
146 Author.
147 .RE
148 .SH "COPYRIGHT"
149 .br