summaryrefslogtreecommitdiff
path: root/src/lib/libc/net/getaddrinfo.3
diff options
context:
space:
mode:
authoraaron <>1999-07-05 04:41:00 +0000
committeraaron <>1999-07-05 04:41:00 +0000
commitc47037b066169c61c5eefad3368f2da73ca4be54 (patch)
treefa80157fecd0fbb57811f82d8f3ce1366b44a203 /src/lib/libc/net/getaddrinfo.3
parent5f78a44df1a8e524a82445f2fedb382128869a2a (diff)
downloadopenbsd-c47037b066169c61c5eefad3368f2da73ca4be54.tar.gz
openbsd-c47037b066169c61c5eefad3368f2da73ca4be54.tar.bz2
openbsd-c47037b066169c61c5eefad3368f2da73ca4be54.zip
repairs; better English, formatting, etc.
Diffstat (limited to 'src/lib/libc/net/getaddrinfo.3')
-rw-r--r--src/lib/libc/net/getaddrinfo.397
1 files changed, 49 insertions, 48 deletions
diff --git a/src/lib/libc/net/getaddrinfo.3 b/src/lib/libc/net/getaddrinfo.3
index 5d644ba549..6bf86d48cf 100644
--- a/src/lib/libc/net/getaddrinfo.3
+++ b/src/lib/libc/net/getaddrinfo.3
@@ -1,3 +1,4 @@
1.\" $OpenBSD: getaddrinfo.3,v 1.3 1999/07/05 04:40:59 aaron Exp $
1.\" Copyright (c) 1983, 1987, 1991, 1993 2.\" Copyright (c) 1983, 1987, 1991, 1993
2.\" The Regents of the University of California. All rights reserved. 3.\" The Regents of the University of California. All rights reserved.
3.\" 4.\"
@@ -30,13 +31,13 @@
30.\" SUCH DAMAGE. 31.\" SUCH DAMAGE.
31.\" 32.\"
32.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 33.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
33.\" $Id: getaddrinfo.3,v 1.2 1999/07/03 20:26:55 deraadt Exp $ 34.\" $Id: getaddrinfo.3,v 1.3 1999/07/05 04:40:59 aaron Exp $
34.\" 35.\"
35.Dd May 25, 1995 36.Dd May 25, 1995
36.Dt GETADDRINFO 3 37.Dt GETADDRINFO 3
37.Os KAME 38.Os
38.Sh NAME 39.Sh NAME
39.Nm getaddrinfo 40.Nm getaddrinfo ,
40.Nm freeaddrinfo , 41.Nm freeaddrinfo ,
41.Nm gai_strerror 42.Nm gai_strerror
42.Nd nodename-to-address translation in protocol-independent manner 43.Nd nodename-to-address translation in protocol-independent manner
@@ -60,8 +61,10 @@ and
60.Xr getservbyname 3 , 61.Xr getservbyname 3 ,
61but in a more sophisticated manner. 62but in a more sophisticated manner.
62.Pp 63.Pp
63The addrinfo structure is defined as a result of including the 64The
64.Li <netdb.h> 65.Li addrinfo
66structure is defined as a result of including the
67.Aq Pa netdb.h
65header: 68header:
66.Bd -literal -offset 69.Bd -literal -offset
67struct addrinfo { * 70struct addrinfo { *
@@ -82,9 +85,7 @@ and
82.Fa servname 85.Fa servname
83arguments are pointers to null-terminated strings or 86arguments are pointers to null-terminated strings or
84.Dv NULL . 87.Dv NULL .
85One or both of these two arguments must be a 88One or both of these two arguments must be a non-null pointer.
86.Pf non Dv -NULL
87pointer.
88In the normal client scenario, both the 89In the normal client scenario, both the
89.Fa nodename 90.Fa nodename
90and 91and
@@ -93,15 +94,11 @@ are specified.
93In the normal server scenario, only the 94In the normal server scenario, only the
94.Fa servname 95.Fa servname
95is specified. 96is specified.
96A 97A non-null
97.Pf non Dv -NULL
98.Fa nodename 98.Fa nodename
99string can be either a node name or a numeric host address string 99string can be either a node name or a numeric host address string
100.Po 100(i.e., a dotted-decimal IPv4 address or an IPv6 hex address)
101i.e., a dotted-decimal IPv4 address or an IPv6 hex address 101A non-null
102.Pc .
103A
104.Pf non Dv -NULL
105.Fa servname 102.Fa servname
106string can be either a service name or a decimal port number. 103string can be either a service name or a decimal port number.
107.Pp 104.Pp
@@ -117,9 +114,7 @@ structure all members other than
117.Fa ai_socktype , 114.Fa ai_socktype ,
118and 115and
119.Fa ai_protocol 116.Fa ai_protocol
120must be zero or a 117must be zero or a null pointer.
121.Dv NULL
122pointer.
123A value of 118A value of
124.Dv PF_UNSPEC 119.Dv PF_UNSPEC
125for 120for
@@ -149,13 +144,12 @@ when
149is called. 144is called.
150If the third argument to 145If the third argument to
151.Fn getaddrinfo 146.Fn getaddrinfo
152is a 147is a null pointer, this is the same as if the caller had filled in an
153.Dv NULL
154pointer, this is the same as if the caller had filled in an
155.Li addrinfo 148.Li addrinfo
156structure initialized to zero with 149structure initialized to zero with
157.Fa ai_family 150.Fa ai_family
158set to PF_UNSPEC. 151set to
152.Dv PF_UNSPEC .
159.Pp 153.Pp
160Upon successful return a pointer to a linked list of one or more 154Upon successful return a pointer to a linked list of one or more
161.Li addrinfo 155.Li addrinfo
@@ -164,9 +158,7 @@ The caller can process each
164.Li addrinfo 158.Li addrinfo
165structure in this list by following the 159structure in this list by following the
166.Fa ai_next 160.Fa ai_next
167pointer, until a 161pointer, until a null pointer is encountered.
168.Dv NULL
169pointer is encountered.
170In each returned 162In each returned
171.Li addrinfo 163.Li addrinfo
172structure the three members 164structure the three members
@@ -197,9 +189,7 @@ structure in a call to
197.Fn bind . 189.Fn bind .
198In this case, if the 190In this case, if the
199.Fa nodename 191.Fa nodename
200argument is a 192argument is a null pointer, then the IP address portion of the socket
201.Dv NULL
202pointer, then the IP address portion of the socket
203address structure will be set to 193address structure will be set to
204.Dv INADDR_ANY 194.Dv INADDR_ANY
205for an IPv4 address or 195for an IPv4 address or
@@ -218,14 +208,13 @@ call to
218.Pq for a connection-oriented protocol 208.Pq for a connection-oriented protocol
219or either 209or either
220.Fn connect , 210.Fn connect ,
221.Fn sendto , or 211.Fn sendto ,
212or
222.Fn sendmsg 213.Fn sendmsg
223.Pq for a connectionless protocol . 214.Pq for a connectionless protocol .
224In this case, if the 215In this case, if the
225.Fa nodename 216.Fa nodename
226argument is a 217argument is a null pointer, then the IP address portion of the
227.Dv NULL
228pointer, then the IP address portion of the
229socket address structure will be set to the loopback address. 218socket address structure will be set to the loopback address.
230.Pp 219.Pp
231If the 220If the
@@ -248,8 +237,7 @@ bit is set in the
248.Fa ai_flags 237.Fa ai_flags
249member of the 238member of the
250.Fa hints 239.Fa hints
251structure, then a 240structure, then a non-null
252.Pf non Dv -NULL
253.Fa nodename 241.Fa nodename
254string must be a numeric host address string. 242string must be a numeric host address string.
255Otherwise an error of 243Otherwise an error of
@@ -263,7 +251,7 @@ All of the information returned by
263is dynamically allocated: 251is dynamically allocated:
264the 252the
265.Li addrinfo 253.Li addrinfo
266structures, and the socket address structures and canonical node name 254structures, the socket address structures, and canonical node name
267strings pointed to by the addrinfo structures. 255strings pointed to by the addrinfo structures.
268To return this information to the system the function 256To return this information to the system the function
269.Fn freeaddrinfo 257.Fn freeaddrinfo
@@ -303,32 +291,44 @@ Error return status from
303.Fn getaddrinfo 291.Fn getaddrinfo
304is zero on success and non-zero on errors. 292is zero on success and non-zero on errors.
305Non-zero error codes are defined in 293Non-zero error codes are defined in
306.Li <netdb.h> , 294.Aq Pa netdb.h ,
307and as follows: 295and as follows:
308.Pp 296.Pp
309.Bl -tag -width EAI_ADDRFAMILY -compact 297.Bl -tag -width EAI_ADDRFAMILY -compact
310.It Dv EAI_ADDRFAMILY 298.It Dv EAI_ADDRFAMILY
311address family for nodename not supported 299Address family for
300.Fa nodename
301not supported.
312.It Dv EAI_AGAIN 302.It Dv EAI_AGAIN
313temporary failure in name resolution 303Temporary failure in name resolution.
314.It Dv EAI_BADFLAGS 304.It Dv EAI_BADFLAGS
315invalid value for ai_flags 305Invalid value for
306.Fa ai_flags .
316.It Dv EAI_FAIL 307.It Dv EAI_FAIL
317non-recoverable failure in name resolution 308Non-recoverable failure in name resolution.
318.It Dv EAI_FAMILY 309.It Dv EAI_FAMILY
319ai_family not supported 310.Fa ai_family
311not supported.
320.It Dv EAI_MEMORY 312.It Dv EAI_MEMORY
321memory allocation failure 313Memory allocation failure.
322.It Dv EAI_NODATA 314.It Dv EAI_NODATA
323no address associated with nodename 315No address associated with
316.Fa nodename .
324.It Dv EAI_NONAME 317.It Dv EAI_NONAME
325nodename nor servname provided, or not known 318.Fa nodename
319nor
320.Fa servname
321provided, or not known.
326.It Dv EAI_SERVICE 322.It Dv EAI_SERVICE
327servname not supported for ai_socktype 323.Fa servname
324not supported for
325.Fa ai_socktype .
328.It Dv EAI_SOCKTYPE 326.It Dv EAI_SOCKTYPE
329ai_socktype not supported 327.Fa ai_socktype
328not supported.
330.It Dv EAI_SYSTEM 329.It Dv EAI_SYSTEM
331system error returned in errno 330System error returned in
331.Va errno .
332.El 332.El
333.Pp 333.Pp
334If called with proper argument, 334If called with proper argument,
@@ -353,7 +353,8 @@ R. Gilligan, S. Thomson, J. Bound, and W. Stevens,
353The 353The
354.Fn getaddrinfo 354.Fn getaddrinfo
355function is defined IEEE POSIX 1003.1g draft specification, 355function is defined IEEE POSIX 1003.1g draft specification,
356and documented in ``Basic Socket Interface Extensions for IPv6'' 356and documented in
357.Dq Basic Socket Interface Extensions for IPv6
357.Pq RFC2533 . 358.Pq RFC2533 .
358.Sh BUGS 359.Sh BUGS
359The text was shamelessly copied from RFC2553. 360The text was shamelessly copied from RFC2553.