diff options
author | nik <nik@FreeBSD.org> | 2001-02-10 07:48:01 +0000 |
---|---|---|
committer | nik <nik@FreeBSD.org> | 2001-02-10 07:48:01 +0000 |
commit | 677b714f57f1489dd0c1e6d930cbc41205ca7830 (patch) | |
tree | 8c699570885d9e1992c96ec360bc76db314ab833 | |
parent | 38719f8bca4e40c2972b6cae348e1e72417fbe72 (diff) | |
download | FreeBSD-src-677b714f57f1489dd0c1e6d930cbc41205ca7830.zip FreeBSD-src-677b714f57f1489dd0c1e6d930cbc41205ca7830.tar.gz |
Improve language and code examples.
PR: docs/24961
Submmitted by: Tony Finch <dot@dotat.at>
-rw-r--r-- | lib/libc/net/getaddrinfo.3 | 72 |
1 files changed, 41 insertions, 31 deletions
diff --git a/lib/libc/net/getaddrinfo.3 b/lib/libc/net/getaddrinfo.3 index 152e9d9..9585607 100644 --- a/lib/libc/net/getaddrinfo.3 +++ b/lib/libc/net/getaddrinfo.3 @@ -74,7 +74,7 @@ structure is defined as a result of including the .Aq Pa netdb.h header: .Bd -literal -offset -struct addrinfo { * +struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ int ai_family; /* PF_xxx */ int ai_socktype; /* SOCK_xxx */ @@ -272,17 +272,17 @@ from being called. .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 @@ If you specify a 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 @@ while you set 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 @@ and .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 @@ If the argument is not one of the 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 @@ The following code tries to connect to 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 @@ if (error) { /*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 @@ if (s < 0) { 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 @@ for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { 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 @@ System error returned in .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 |