SOGaiStrerror / SOGetAddrInfo / SOGetAddrInfoRSU / SOFreeAddrInfo

Syntax

#include <cafe.h>
#include <cafe/network.h>

int SOGetAddrInfo(const char *node, const char *service,
                const struct addrinfo *hints,
                struct addrinfo **res);

int SOGetAddrInfoRSU(const char *node, const char *service,
                const struct addrinfo *hints,
                struct addrinfo **res);

void SOFreeAddrInfo(struct addrinfo *res);

const char *SOGaiStrerror(int errcode);

Parameters

node Numerical address or network hostname.
service Service name or port number.
hints addrinfo struct selecting socket return criteria.
res Linked list of addrinfo structures.

Return Values

0 Success.
EAI_AGAIN Name could not be resolved. Future attempts may succeed.
EAI_BADFLAGS Specified flags are invalid.
EAI_FAIL An unrecoverable error occurred.
EAI_FAMILY Unknown address family.
EAI_MEMORY Memory allocation failure.
EAI_NONAME Name could not be resolved.
EAI_SERVICE Unknown service name.
EAI_SOCKTYPE Unknown socket type.
EAI_SYSTEM A system error occurred.

Description

SOGetAddrInfo translates a node name to a set of socket addresses. SOGetAddrInfoRSU has an identical signature and behavior to SOGetAddrInfo (which was left unchanged for compatibility purposes) but uses approximately 14K less of stack space. Only IPV4 is currently supported.

SOFreeAddrInfo releases the linked list of SOAddrInfo structures returned by SOGetAddrInfo.

SOGaiStrerror translates SOGetAddrInfo and SOFreeAddrInfo error codes into human-readable strings.

SOGetAddrInfo, SOFreeAddrInfo and SOGaiStrerror are thread-safe.

The hostname and servname arguments are either pointers to NULL-terminated strings or the null pointer. An acceptable value for hostname is either a valid hostname or a numeric host address string consisting of a dotted decimal IPv4 address. The servname is a decimal port number (there is no support for resolving by service name). At least one of hostname and servname must be non-null.

hints is an optional pointer to an addrinfo struct.

This structure can be used to provide hints concerning the type of socket that the caller supports or wishes to use. The caller can supply the following structure elements in hints:

ai_family The protocol family that should be used. Must be AF_INET or AF_UNSPEC.
ai_socktype Denotes the type of socket that is wanted: SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW. When ai_socktype is zero the caller will accept any socket type.
ai_protocol Indicates which transport protocol is desired, IPPROTO_UDP or IPPROTO_TCP. If ai_protocol is zero the caller will accept any protocol.
ai_flags ai_flags is formed by OR'ing the following values:
AI_CANONNAME If the AI_CANONNAME bit is set, a successful call to SOGetAddrInfo will return a NULL-terminated string containing the canonical name of the specified hostname in the ai_canonname element of the first addrinfo structure returned.
AI_NUMERICHOST Inhibits DNS queries (name must be a valid dotted quad string).
AI_PASSIVE If the AI_PASSIVE bit is set it indicates that the returned socket address structure is intended for use in a call to SOBind. In this case, if the hostname argument is the null pointer, then the IP address portion of the socket address structure will be set to INADDR_ANY for an IPv4 address. If the AI_PASSIVE bit is not set, the returned socket address structure will be ready for use in a call to SOConnect for a connection-oriented protocol or SOConnect, SOSendTo, or SOSendMsg if a connectionless protocol was chosen. The IP address portion of the socket address structure will be set to the loopback address if hostname is the null pointer and AI_PASSIVE is not set.

All of the information returned by SOGetAddrInfo is dynamically allocated: the addrinfo structures themselves as well as the socket address structures and the canonical hostname strings included in the addrinfo structures.

Memory allocated for the dynamically allocated structures created by a successful call to SOGetAddrInfo is released by the SOFreeAddrInfo function. The ai pointer should be a addrinfo structure created by a call to SOGetAddrInfo.

NOTE:
SOGetAddrInfo allocates about 15K bytes from the user stack per call. If multiple threads have concurrent, in-progess calls, a large amount of stack memory can be consumed. SOGetAddrInfoRSU behaves identically to SOGetAddrInfo but reduces stack usage to 1.5K bytes per call.

Do Not Call From

SOFreeAddrInfo

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

SOGaiStrerror

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

SOGetAddrInfo

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

SOGetAddrInfoRSU

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

Revision History

2014-07-01 Document RSU variant.
2014-02-18 Note about stack consumption.
2012-08-16 Cleanup pass.
2012-02-14 Clarified that servname is limited to numeric port numbers.
2011-08-21 Initial version.


CONFIDENTIAL