From 39e6e65a2c5a3312f365d59f23c469641e049c82 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Wed, 19 Aug 1998 21:32:28 +0000 Subject: Base files --- c/src/libnetworking/libc/addr2ascii.3 | 216 ++++++++++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 c/src/libnetworking/libc/addr2ascii.3 (limited to 'c/src/libnetworking/libc/addr2ascii.3') diff --git a/c/src/libnetworking/libc/addr2ascii.3 b/c/src/libnetworking/libc/addr2ascii.3 new file mode 100644 index 0000000000..21ebe2a22f --- /dev/null +++ b/c/src/libnetworking/libc/addr2ascii.3 @@ -0,0 +1,216 @@ +.\" +.\" 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 $ +.\" +.Dd June 13, 1996 +.Dt ADDR2ASCII 3 +.Os +.Sh NAME +.Nm addr2ascii , +.Nm ascii2addr +.Nd Generic address formatting routines +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.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 +.Pq in Aq Pa netinet/in.h +.It Dv AF_LINK +.Li struct sockaddr_dl +.Pq in Aq Pa net/if_dl.h +.\" .It Dv AF_INET6 +.\" .Li struct in6_addr +.\" .Pq 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 +#include +#include +#include + +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 [EPROTONOSUPPORT] +.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. -- cgit v1.2.3