Attachment #13041 for bug #24961

View | Details | Raw Unified | Return to bug 24961
Collapse All | Expand All




.Pp
The arguments to
.Fn getaddrinfo
must be sufficiently consistent and unambiguous.
Here are some problem cases you may encounter:
.Bl -bullet
.It
.Fn getaddrinfo
will fail if the members in the
.Fa hints
structure are not consistent.
For example, for internet address families,
.Fn getaddrinfo
will fail if you specify
.Dv SOCK_STREAM
to
.Fa ai_socktype

which is defined only for certain
.Fa ai_socktype ,
.Fn getaddrinfo
will fail because the arguments are not consistent.
For example,
.Fn getaddrinfo
will return an error if you ask for
.Dq Li tftp
service on
.Dv SOCK_STREAM .

to
.Dv SOCK_RAW ,
.Fn getaddrinfo
will fail, because service names are not defined for the internet
.Dv SOCK_RAW
space.
.It

.Fa ai_protocol
unspecified,
.Fn getaddrinfo
will fail.
This is because the numeric
.Fa servname
does not identify any socket type, and

values, the function still returns a pointer to a string whose contents
indicate an unknown error.
.\"
.Sh EXTENSIONS
This implementation supports numeric IPv6 address notation with the
experimental scope identifier.
By appending a percent sign and scope identifier to the address, you
can specify the value of the
.Li sin6_scope_id
field of the socket address.
This makes management of scoped address easier,
and allows cut-and-paste input of scoped addresses.
.Pp
At the moment the code supports only link-local addresses in this format.
The scope identifier is hardcoded to name of hardware interface associated
with the link,
.Po
such as
.Li ne0
.Pc .
For example,
.Dq Li fe80::1%ne0 ,
which means
.Do
.Li fe80::1
on the link associated with the
.Li ne0
interface
.Dc .
.Pp
This implementation is still very experimental and non-standard.
The current implementation assumes a one-to-one relationship between
interfaces and links, which is not necessarily true according to the
specification.
.\"
.Sh EXAMPLES
The following code tries to connect to

service
.Dq Li http .
via stream socket.
It loops through all the addresses available, regardless of the address family.
If the destination resolves to an IPv4 address, it will use an
.Dv AF_INET
socket.
Similarly, if it resolves to IPv6, an
.Dv AF_INET6
socket is used.
Observe that there is no hardcoded reference to particular address family.

	/*NOTREACHED*/
}
s = -1;
cause = "no addresses";
errno = EADDRNOTAVAIL;
for (res = res0; res; res = res->ai_next) {
	s = socket(res->ai_family, res->ai_socktype,
	    res->ai_protocol);

freeaddrinfo(res0);
.Ed
.Pp
The following example tries to open a wildcard listening socket onto service
.Dq Li http ,
for all the address families available.
.Bd -literal -offset indent

		continue;
	}

	if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
		cause = "connect";
		close(s[nsock]);
		continue;
	}

	if (listen(s[nsock], SOMAXCONN) < 0) {
		cause = "listen";
		close(s[nsock]);
		continue;
	}

	nsock++;
}
if (nsock == 0) {

.Va errno .
.El
.Pp
If called with an appropriate argument,
.Fn gai_strerror
returns a pointer to a string describing the given error code.
If the argument is not one of the

Return to bug 24961

Lines 272-288 Link Here

(-)getaddrinfo.3 (-30 / +40 lines)
272	.Pp	272	.Pp
273	The arguments to	273	The arguments to
274	.Fn getaddrinfo	274	.Fn getaddrinfo
275	must sufficiently be consistent and unambiguous.	275	must be sufficiently consistent and unambiguous.
276	Here are pitfall cases you may encounter:	276	Here are some problem cases you may encounter:
277	.Bl -bullet	277	.Bl -bullet
278	.It	278	.It
279	.Fn getaddrinfo	279	.Fn getaddrinfo
280	will raise error if members in	280	will fail if the members in the
281	.Fa hints	281	.Fa hints
282	structure is not consistent.	282	structure are not consistent.
283	For example, for internet address families,	283	For example, for internet address families,
284	.Fn getaddrinfo	284	.Fn getaddrinfo
285	will raise error if you specify	285	will fail if you specify
286	.Dv SOCK_STREAM	286	.Dv SOCK_STREAM
287	to	287	to
288	.Fa ai_socktype	288	.Fa ai_socktype
Lines 296-305 Link Here
296	which is defined only for certain	296	which is defined only for certain
297	.Fa ai_socktype ,	297	.Fa ai_socktype ,
298	.Fn getaddrinfo	298	.Fn getaddrinfo
299	will raise error because the arguments are not consistent.	299	will fail because the arguments are not consistent.
300	For example,	300	For example,
301	.Fn getaddrinfo	301	.Fn getaddrinfo
302	will raise error if you ask for	302	will return an error if you ask for
303	.Dq Li tftp	303	.Dq Li tftp
304	service on	304	service on
305	.Dv SOCK_STREAM .	305	.Dv SOCK_STREAM .
Lines 311-317 Link Here
311	to	311	to
312	.Dv SOCK_RAW ,	312	.Dv SOCK_RAW ,
313	.Fn getaddrinfo	313	.Fn getaddrinfo
314	will raise error, because service names are not defined for the internet	314	will fail, because service names are not defined for the internet
315	.Dv SOCK_RAW	315	.Dv SOCK_RAW
316	space.	316	space.
317	.It	317	.It
Lines 323-329 Link Here
323	.Fa ai_protocol	323	.Fa ai_protocol
324	unspecified,	324	unspecified,
325	.Fn getaddrinfo	325	.Fn getaddrinfo
326	will raise error.	326	will fail.
327	This is because the numeric	327	This is because the numeric
328	.Fa servname	328	.Fa servname
329	does not identify any socket type, and	329	does not identify any socket type, and
Lines 366-400 Link Here
366	values, the function still returns a pointer to a string whose contents	366	values, the function still returns a pointer to a string whose contents
367	indicate an unknown error.	367	indicate an unknown error.
368	.\"	368	.\"
369	.Sh EXTENSION	369	.Sh EXTENSIONS
370	The implementation allows experimental numeric IPv6 address notation with	370	This implementation supports numeric IPv6 address notation with the
371	scope identifier.	371	experimental scope identifier.
372	By appending atmark and scope identifier to addresses, you can fill	372	By appending a percent sign and scope identifier to the address, you
		373	can specify the value of the
373	.Li sin6_scope_id	374	.Li sin6_scope_id
374	field for addresses.	375	field of the socket address.
375	This would make management of scoped address easier,	376	This makes management of scoped address easier,
376	and allows cut-and-paste input of scoped address.	377	and allows cut-and-paste input of scoped addresses.
377	.Pp	378	.Pp
378	At this moment the code supports only link-local addresses with the format.	379	At the moment the code supports only link-local addresses in this format.
379	Scope identifier is hardcoded to name of hardware interface associated	380	The scope identifier is hardcoded to name of hardware interface associated
380	with the link.	381	with the link,
381	.Po	382	.Po
382	such as	383	such as
383	.Li ne0	384	.Li ne0
384	.Pc .	385	.Pc .
385	Example would be like	386	For example,
386	.Dq Li fe80::1%ne0 ,	387	.Dq Li fe80::1%ne0 ,
387	which means	388	which means
388	.Do	389	.Do
389	.Li fe80::1	390	.Li fe80::1
390	on the link associated with	391	on the link associated with the
391	.Li ne0	392	.Li ne0
392	interface	393	interface
393	.Dc .	394	.Dc .
394	.Pp	395	.Pp
395	The implementation is still very experimental and non-standard.	396	This implementation is still very experimental and non-standard.
396	The current implementation assumes one-by-one relationship between	397	The current implementation assumes a one-to-one relationship between
397	interface and link, which is not necessarily true from the specification.	398	interfaces and links, which is not necessarily true according to the
		399	specification.
398	.\"	400	.\"
399	.Sh EXAMPLES	401	.Sh EXAMPLES
400	The following code tries to connect to	402	The following code tries to connect to
Lines 402-412 Link Here
402	service	404	service
403	.Dq Li http .	405	.Dq Li http .
404	via stream socket.	406	via stream socket.
405	It loops through all the addresses available, regardless from address family.	407	It loops through all the addresses available, regardless of the address family.
406	If the destination resolves to IPv4 address, it will use	408	If the destination resolves to an IPv4 address, it will use an
407	.Dv AF_INET	409	.Dv AF_INET
408	socket.	410	socket.
409	Similarly, if it resolves to IPv6,	411	Similarly, if it resolves to IPv6, an
410	.Dv AF_INET6	412	.Dv AF_INET6
411	socket is used.	413	socket is used.
412	Observe that there is no hardcoded reference to particular address family.	414	Observe that there is no hardcoded reference to particular address family.
Lines 428-433 Link Here
428	/NOTREACHED/	430	/NOTREACHED/
429	}	431	}
430	s = -1;	432	s = -1;
		433	cause = "no addresses";
		434	errno = EADDRNOTAVAIL;
431	for (res = res0; res; res = res->ai_next) {	435	for (res = res0; res; res = res->ai_next) {
432	s = socket(res->ai_family, res->ai_socktype,	436	s = socket(res->ai_family, res->ai_socktype,
433	res->ai_protocol);	437	res->ai_protocol);
Lines 452-458 Link Here
452	freeaddrinfo(res0);	456	freeaddrinfo(res0);
453	.Ed	457	.Ed
454	.Pp	458	.Pp
455	The following example tries to open wildcard listening socket onto service	459	The following example tries to open a wildcard listening socket onto service
456	.Dq Li http ,	460	.Dq Li http ,
457	for all the address families available.	461	for all the address families available.
458	.Bd -literal -offset indent	462	.Bd -literal -offset indent
Lines 480-491 Link Here
480	continue;	484	continue;
481	}	485	}
482		486
483	if (connect(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {	487	if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
484	cause = "connect";	488	cause = "connect";
485	close(s[nsock]);	489	close(s[nsock]);
486	continue;	490	continue;
487	}	491	}
488		492
		493	if (listen(s[nsock], SOMAXCONN) < 0) {
		494	cause = "listen";
		495	close(s[nsock]);
		496	continue;
		497	}
		498
489	nsock++;	499	nsock++;
490	}	500	}
491	if (nsock == 0) {	501	if (nsock == 0) {
Lines 547-553 Link Here
547	.Va errno .	557	.Va errno .
548	.El	558	.El
549	.Pp	559	.Pp
550	If called with proper argument,	560	If called with an appropriate argument,
551	.Fn gai_strerror	561	.Fn gai_strerror
552	returns a pointer to a string describing the given error code.	562	returns a pointer to a string describing the given error code.
553	If the argument is not one of the	563	If the argument is not one of the