c4d9468ea0
Avoid using parenthesis enclosure macros (.Pq and .Po/.Pc) with plain text. Not only this slows down the mdoc(7) processing significantly, but it also has an undesired (in this case) effect of disabling hyphenation within the entire enclosed block.
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$
|
|
.\"
|
|
.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
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <netinet/in.h>
|
|
.Fd #include <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.
|