223 lines
5.9 KiB
Groff
223 lines
5.9 KiB
Groff
.\"
|
|
.\" Copyright 1996 Massachusetts Institute of Technology
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software and
|
|
.\" its documentation for any purpose and without fee is hereby
|
|
.\" granted, provided that both the above copyright notice and this
|
|
.\" permission notice appear in all copies, that both the above
|
|
.\" copyright notice and this permission notice appear in all
|
|
.\" supporting documentation, and that the name of M.I.T. not be used
|
|
.\" in advertising or publicity pertaining to distribution of the
|
|
.\" software without specific, written prior permission. M.I.T. makes
|
|
.\" no representations about the suitability of this software for any
|
|
.\" purpose. It is provided "as is" without express or implied
|
|
.\" warranty.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
|
|
.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
|
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
|
|
.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
|
|
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
|
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $ANA: addr2ascii.3,v 1.1 1996/06/13 18:41:46 wollman Exp $
|
|
.\" $FreeBSD: src/lib/libc/net/addr2ascii.3,v 1.12 2001/10/01 16:08:55 ru Exp $
|
|
.\"
|
|
.Dd June 13, 1996
|
|
.Dt ADDR2ASCII 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm addr2ascii ,
|
|
.Nm ascii2addr
|
|
.Nd Generic address formatting routines
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In netinet/in.h
|
|
.In arpa/inet.h
|
|
.Ft "char *"
|
|
.Fn addr2ascii "int af" "const void *addrp" "int len" "char *buf"
|
|
.Ft int
|
|
.Fn ascii2addr "int af" "const char *ascii" "void *result"
|
|
.Sh DESCRIPTION
|
|
The routines
|
|
.Fn addr2ascii
|
|
and
|
|
.Fn ascii2addr
|
|
are used to convert network addresses between binary form and a
|
|
printable form appropriate to the address family. Both functions take
|
|
an
|
|
.Fa af
|
|
argument, specifying the address family to be used in the conversion
|
|
process.
|
|
(Currently, only the
|
|
.Dv AF_INET
|
|
and
|
|
.Dv AF_LINK
|
|
address families are supported.)
|
|
.Pp
|
|
The
|
|
.Fn addr2ascii
|
|
function
|
|
is used to convert binary, network-format addresses into printable
|
|
form. In addition to
|
|
.Fa af ,
|
|
there are three other arguments. The
|
|
.Fa addrp
|
|
argument is a pointer to the network address to be converted.
|
|
The
|
|
.Fa len
|
|
argument is the length of the address. The
|
|
.Fa buf
|
|
argument is an optional pointer to a caller-allocated buffer to hold
|
|
the result; if a null pointer is passed,
|
|
.Fn addr2ascii
|
|
uses a statically-allocated buffer.
|
|
.Pp
|
|
The
|
|
.Fn ascii2addr
|
|
function performs the inverse operation to
|
|
.Fn addr2ascii .
|
|
In addition to
|
|
.Fa af ,
|
|
it takes two parameters,
|
|
.Fa ascii
|
|
and
|
|
.Fa result .
|
|
The
|
|
.Fa ascii
|
|
parameter is a pointer to the string which is to be converted into
|
|
binary. The
|
|
.Fa result
|
|
parameter is a pointer to an appropriate network address structure for
|
|
the specified family.
|
|
.Pp
|
|
The following gives the appropriate structure to use for binary
|
|
addresses in the specified family:
|
|
.Pp
|
|
.Bl -tag -width AF_INETxxxx -compact
|
|
.It Dv AF_INET
|
|
.Li struct in_addr
|
|
(in
|
|
.Aq Pa netinet/in.h )
|
|
.It Dv AF_LINK
|
|
.Li struct sockaddr_dl
|
|
(in
|
|
.Aq Pa net/if_dl.h )
|
|
.\" .It Dv AF_INET6
|
|
.\" .Li struct in6_addr
|
|
.\" (in
|
|
.\" .Aq Pa netinet6/in6.h )
|
|
.El
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn 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
|
|
.Fn ascii2addr
|
|
function returns the length of the binary address in bytes, or -1 on
|
|
failure.
|
|
.Sh EXAMPLES
|
|
The
|
|
.Xr inet 3
|
|
functions
|
|
.Fn inet_ntoa
|
|
and
|
|
.Fn inet_aton
|
|
could be implemented thusly:
|
|
.Bd -literal -offset indent
|
|
#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));
|
|
}
|
|
.Ed
|
|
.Pp
|
|
In actuality, this cannot be done because
|
|
.Fn addr2ascii
|
|
and
|
|
.Fn ascii2addr
|
|
are implemented in terms of the
|
|
.Xr inet 3
|
|
functions, rather than the other way around.
|
|
.Sh ERRORS
|
|
When a failure is returned,
|
|
.Li errno
|
|
is set to one of the following values:
|
|
.Bl -tag -width Er
|
|
.It Bq Er ENAMETOOLONG
|
|
The
|
|
.Fn addr2ascii
|
|
routine was passed a
|
|
.Fa len
|
|
parameter which was inappropriate for the address family given by
|
|
.Fa af .
|
|
.It Bq Er EPROTONOSUPPORT
|
|
Either routine was passed an
|
|
.Fa af
|
|
parameter other than
|
|
.Dv AF_INET
|
|
or
|
|
.Dv AF_LINK .
|
|
.It Bq Er EINVAL
|
|
The string passed to
|
|
.Fn ascii2addr
|
|
was improperly formatted for address family
|
|
.Fa af .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr inet 3 ,
|
|
.Xr linkaddr 3 ,
|
|
.Xr inet 4
|
|
.Sh HISTORY
|
|
An interface close to this one was originally suggested by Craig
|
|
Partridge. This particular interface originally appeared in the
|
|
.Tn INRIA
|
|
.Tn IPv6
|
|
implementation.
|
|
.Sh AUTHORS
|
|
Code and documentation by
|
|
.An Garrett A. Wollman ,
|
|
MIT Laboratory for Computer Science.
|
|
.Sh BUGS
|
|
The original implementations supported IPv6. This support should
|
|
eventually be resurrected. The
|
|
.Tn NRL
|
|
implementation also included support for the
|
|
.Dv AF_ISO
|
|
and
|
|
.Dv AF_NS
|
|
address families.
|
|
.Pp
|
|
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
|
|
.Dq Li "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.
|