SOGetNameInfo

Syntax

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

int SOGetNameInfo(const struct sockaddr *sa, socklen_t salen,
		  char *host, size_t hostlen,
		  char *serv, size_t servlen, int flags);

Parameters

sa Pointer to generic socket structure.
salen Size of sa structure.
host Caller-allocated buffer for host string.
hostlen Size of host string buffer.
serv Caller-allocated buffer for service name string.
servlen Size of service name string buffer.
flags Operational flags.

Return Values

0 indicates success.

Errors

EAI_AGAIN
Name could not be resolved. Future attempts may succeed.
EAI_BADFLAGS
Specified flags is invalid.
EAI_FAIL
A non-recoverable 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

The SOGetNameInfo function is the inverse of SOGetAddrInfo; it converts a socket address to a corresponding host and service. SOGetNameInfo currently supports IPv4 only.

SOGetNameInfo is thread-safe.

The sockaddr structure sa should point to a sockaddr_in structure (IPv4) that is salen bytes long.

The host and service names associated with sa are stored in host and serv, which have length parameters hostlen and servlen. The maximum value for hostlen is NI_MAXHOST, and the maximum value for servlen is NI_MAXSERV, as defined by <netdb.h>. If a length parameter is zero, no string will be stored. Otherwise, enough space must be provided to store the hostname or service string plus a byte for the NULL terminator.

The flags argument is formed by OR'ing the following values:

NI_NOFQDN A fully qualified domain name is not required for local hosts. The local part of the fully qualified domain name is returned instead.
NI_NUMERICHOST Return the address in numeric form, as if calling inet_ntop, instead of a hostname.
NI_NAMEREQD A name is required. If the hostname cannot be found in DNS and this flag is set, a nonzero error code is returned. If the hostname is not found and the flag is not set, the address is returned in numeric form.
NI_NUMERICSERV The service name is returned as a digit string representing the port number.
NI_DGRAM Specifies that the service being looked up is a datagram service.

Do Not Call From

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

2012/08/16 Cleanup pass.
2011/08/21 Initial version.


CONFIDENTIAL