addr2ascii(3)
NAME
addr2ascii, ascii2addr - Generic address formatting routines
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <arpa/inet.h> char * addr2ascii(int af, const void *addrp, int len, char *buf); int ascii2addr(int af, const char *ascii, void *result);
DESCRIPTION
- The routines addr2ascii() and ascii2addr() are used to con
- vert network
addresses between binary form and a printable form appropri - ate to the
address family. Both functions take an af argument, speci - fying the
address family to be used in the conversion process. (Cur - rently, only
the AF_INET and AF_LINK address families are supported.) - The addr2ascii() function is used to convert binary, net
- work-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 bi
- nary addresses
in the specified family: - AF_INET struct in_addr (in
AF_LINK struct sockaddr_dl (in - AF_INET and AF_LINK constants are defined in
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 re - turns 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 fol
- lowing 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 im
- properly for
- matted for address family af.
SEE ALSO
HISTORY
- An interface close to this one was originally suggested by
- Craig Partridge. This particular interface originally appeared in
- the INRIA IPv6
implementation.
AUTHORS
- Code and documentation by Garrett A. Wollman, MIT Laboratory
- for Computer
Science.
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 genericity 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 ar - bitrary
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. - BSD June 13, 1996