addr2ascii3

Usage

Library

Standard C Library (libc, -lc)

Overview

The routines addr2ascii() and ascii2addr() are used to convert network addresses between binary form and a printable form appropriate to the address family. Both functions take an af argument, specifying the address family to be used in the conversion process. (Currently, only the AF_INET and AF_LINK address families are supported.)

The addr2ascii() function is used to convert binary, network-format addresses into printable form. In addition to af, there are three other arguments. The addrp argument is a pointer to the network address to be converted. The len argument is the length of the address. The buf argument is an optional pointer to a caller-allocated buffer to hold the result; if a null pointer is passed, addr2ascii() uses a statically-allocated buffer.

The ascii2addr() function performs the inverse operation to addr2ascii(). In addition to af, it takes two arguments, ascii and result. The ascii argument is a pointer to the string which is to be converted into binary. The result argument is a pointer to an appropriate network address structure for the specified family.

The following gives the appropriate structure to use for binary addresses in the specified family:

AF_INET

struct in_addr (in ⟨arpa/inet.h⟩)

AF_LINK

struct sockaddr_dl (in ⟨net/if_dl.h⟩)

AF_INET and AF_LINK constants are defined in ⟨sys/socket.h⟩

Return values

The addr2ascii() function returns the address of the buffer it was passed, or a static buffer if the a null pointer was passed; on failure, it returns a null pointer. The ascii2addr() function returns the length of the binary address in bytes, or -1 on failure.

Examples

The inet(3) functions inet_ntoa() and inet_aton() could be implemented thusly:

#include <sys/socket.h>
#include <arpa/inet.h>
char *
inet_ntoa(struct in_addr addr)
{
	return addr2ascii(AF_INET, &addr, sizeof addr, 0);
}
int
inet_aton(const char *ascii, struct in_addr *addr)
{
	return (ascii2addr(AF_INET, ascii, addr)
	    == sizeof(*addr));
}

In actuality, this cannot be done because addr2ascii() and ascii2addr() are implemented in terms of the inet(3) functions, rather than the other way around.

Errors

When a failure is returned, errno is set to one of the following values:

[ENAMETOOLONG]

The addr2ascii() routine was passed a len argument which was inappropriate for the address family given by af.

[EPROTONOSUPPORT]

Either routine was passed an af argument other than AF_INET or AF_LINK.

[EINVAL]

The string passed to ascii2addr() was improperly formatted for address family af.