addr2ascii(3STDC)

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | ATTRIBUTES | SEE ALSO | BUGS

NAME

addr2ascii, ascii2addr- generic address formatting routines

SYNOPSIS

$(OS_DIR)/lib/libc.a
#include <sys/types.h>
#include <netinet/in.h>
#include <arpa/inet.h>

char * addr2ascii(int af, const void *addrp, int len, char *buf);
int ascii2addr(int af, const char *ascii, void *result);

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

DESCRIPTION

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 parameters, ascii and result . The ascii parameter is a pointer to the string which is to be converted into binary. The result parameter is a pointer to an appropriate network address structure for the specified family.

The appropriate structure for binary addresses in the specified family is shown in the following:

    AF_INET      struct in_addr (in <netinet/in.h>)
    AF_LINK      struct sockaddr_dl (in <net/if_dl.h>)

RETURN VALUES

The addr2ascii() function returns the address of the buffer it was passed, or a static buffer if 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(3STDC) , inet_ntoa(3STDC) and inet_aton(3STDC) functions could be implemented as follows:

    #include <sys/types.h>
    #include <sys/socket.h>
    #include <netinet/in.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 reality, this example would not work because addr2ascii() and ascii2addr() are implemented in terms of the inet(3STDC) 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 parameter which was inappropriate for the address family given by af .

EPROTONOSUPPORT

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

EINVAL

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

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

inet(3STDC) , inet(7P)

BUGS

The original implementations supported IPv6. This support should eventually be resurrected. The NRL implementation also included support for the AF_ISO and AF_NS address families.

The generic nature of this interface is somewhat questionable. A truly generic interface would provide a means for determining the length of the buffer to be used so that it could be dynamically allocated, and would always require a ``struct sockaddr'' to hold the binary address. Unfortunately, this is incompatible with existing practice. This limitation means that a routine for printing network addresses from arbitrary address families must still have internal knowledge of the maximum buffer length needed and the appropriate part of the address to use as the binary address.

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | ATTRIBUTES | SEE ALSO | BUGS