Date: Fri, 09 Feb 2001 01:13:22 +0000 From: Tony Finch <dot@dotat.at> To: FreeBSD-gnats-submit@freebsd.org Subject: docs/24961: [PATCH] language and example code improvements for getaddrinfo(3) Message-ID: <E14R27m-0002db-00@hand.dotat.at>
next in thread | raw e-mail | index | archive | help
>Number: 24961
>Category: docs
>Synopsis: [PATCH] language and example code improvements for getaddrinfo(3)
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Thu Feb 08 17:20:01 PST 2001
>Closed-Date:
>Last-Modified:
>Originator: Tony Finch
>Release: FreeBSD 4.2-STABLE i386
>Organization:
Covalent Technologies, Inc.
>Environment:
FreeBSD hand.dotat.at 4.2-STABLE FreeBSD 4.2-STABLE #2: Thu Feb 8 08:45:48 GMT 2001 fanf@hand.dotat.at:/FreeBSD/obj/FreeBSD/releng4/sys/DELL-Latitude-CSx i386
>Description:
The patch below is mostly fixes to Engligh usage; I've also made some
changes to the examples, especially the second one which doesn't
include a call to listen() as the blurb says it should.
>How-To-Repeat:
>Fix:
Index: getaddrinfo.3
===================================================================
RCS file: /home/ncvs/src/lib/libc/net/getaddrinfo.3,v
retrieving revision 1.2.2.5
diff -u -r1.2.2.5 getaddrinfo.3
--- getaddrinfo.3 2001/01/26 13:48:54 1.2.2.5
+++ getaddrinfo.3 2001/02/09 01:08:51
@@ -272,17 +272,17 @@
.Pp
The arguments to
.Fn getaddrinfo
-must sufficiently be consistent and unambiguous.
-Here are pitfall cases you may encounter:
+must be sufficiently consistent and unambiguous.
+Here are some problem cases you may encounter:
.Bl -bullet
.It
.Fn getaddrinfo
-will raise error if members in
+will fail if the members in the
.Fa hints
-structure is not consistent.
+structure are not consistent.
For example, for internet address families,
.Fn getaddrinfo
-will raise error if you specify
+will fail if you specify
.Dv SOCK_STREAM
to
.Fa ai_socktype
@@ -296,10 +296,10 @@
which is defined only for certain
.Fa ai_socktype ,
.Fn getaddrinfo
-will raise error because the arguments are not consistent.
+will fail because the arguments are not consistent.
For example,
.Fn getaddrinfo
-will raise error if you ask for
+will return an error if you ask for
.Dq Li tftp
service on
.Dv SOCK_STREAM .
@@ -311,7 +311,7 @@
to
.Dv SOCK_RAW ,
.Fn getaddrinfo
-will raise error, because service names are not defined for the internet
+will fail, because service names are not defined for the internet
.Dv SOCK_RAW
space.
.It
@@ -323,7 +323,7 @@
.Fa ai_protocol
unspecified,
.Fn getaddrinfo
-will raise error.
+will fail.
This is because the numeric
.Fa servname
does not identify any socket type, and
@@ -366,35 +366,37 @@
values, the function still returns a pointer to a string whose contents
indicate an unknown error.
.\"
-.Sh EXTENSION
-The implementation allows experimental numeric IPv6 address notation with
-scope identifier.
-By appending atmark and scope identifier to addresses, you can fill
+.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 for addresses.
-This would make management of scoped address easier,
-and allows cut-and-paste input of scoped address.
+field of the socket address.
+This makes management of scoped address easier,
+and allows cut-and-paste input of scoped addresses.
.Pp
-At this moment the code supports only link-local addresses with the format.
-Scope identifier is hardcoded to name of hardware interface associated
-with the link.
+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 .
-Example would be like
+For example,
.Dq Li fe80::1%ne0 ,
which means
.Do
.Li fe80::1
-on the link associated with
+on the link associated with the
.Li ne0
interface
.Dc .
.Pp
-The implementation is still very experimental and non-standard.
-The current implementation assumes one-by-one relationship between
-interface and link, which is not necessarily true from the specification.
+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
@@ -402,11 +404,11 @@
service
.Dq Li http .
via stream socket.
-It loops through all the addresses available, regardless from address family.
-If the destination resolves to IPv4 address, it will use
+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,
+Similarly, if it resolves to IPv6, an
.Dv AF_INET6
socket is used.
Observe that there is no hardcoded reference to particular address family.
@@ -428,6 +430,8 @@
/*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);
@@ -452,7 +456,7 @@
freeaddrinfo(res0);
.Ed
.Pp
-The following example tries to open wildcard listening socket onto service
+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
@@ -480,12 +484,18 @@
continue;
}
- if (connect(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
+ 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) {
@@ -547,7 +557,7 @@
.Va errno .
.El
.Pp
-If called with proper argument,
+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
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?E14R27m-0002db-00>