ADDR2ASCII(3) BSD Library Functions Manual ADDR2ASCII(3)

NAME
     aaddddrr22aasscciiii, aasscciiii22aaddddrr - Generic address formatting routines

LLIIBBRRAARRYY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##iinncclluuddee <>

     char *
     aaddddrr22aasscciiii(int af, const void *addrp, int len, char *buf);

     int
     aasscciiii22aaddddrr(int af, const char *ascii, void *result);

DESCRIPTION
     The routines aaddddrr22aasscciiii() and aasscciiii22aaddddrr() 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 AFINET and AFLINK address families are supported.)

     The aaddddrr22aasscciiii() 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 argu-
     ment is an optional pointer to a caller-allocated buffer to hold the
     result; if a null pointer is passed, aaddddrr22aasscciiii() uses a statically-allo-
     cated buffer.

     The aasscciiii22aaddddrr() function performs the inverse operation to aaddddrr22aasscciiii().
     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 struc-
     ture for the specified family.

     The following gives the appropriate structure to use for binary addresses
     in the specified family:

     AFINET      struct inaddr (in )
     AFLINK      struct sockaddrdl (in )

     AFINET and AFLINK constants are defined in 

RETURN VALUES
     The aaddddrr22aasscciiii() 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 aasscciiii22aaddddrr() function returns the length
     of the binary address in bytes, or -1 on failure.

EEXXAAMMPPLLEESS
     The inet(3) functions iinneettnnttooaa() and iinneettaattoonn() could be implemented
     thusly:

           #include 
           #include 

           char *
           inetntoa(struct inaddr addr)
           {
                   return addr2ascii(AFINET, &addr, sizeof addr, 0);
           }

           int
           inetaton(const char *ascii, struct inaddr *addr)
           {
                   return (ascii2addr(AFINET, ascii, addr)
                       == sizeof(*addr));
           }

     In actuality, this cannot be done because aaddddrr22aasscciiii() and aasscciiii22aaddddrr()
     are implemented in terms of the inet(3) functions, rather than the other
     way around.

EERRRROORRSS
     When a failure is returned, errno is set to one of the following values:

     [ENAMETOOLONG]     The aaddddrr22aasscciiii() 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
                        AFINET or AFLINK.

     [EINVAL]           The string passed to aasscciiii22aaddddrr() was improperly for-
                        matted for address family af.

SEE ALSO
     inet(3), linkaddr(3), inet(4)

HISTORY
     An interface close to this one was originally suggested by Craig Par-
     tridge.  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 eventu-
     ally be resurrected.  The NRL implementation also included support for
     the AFISO and AFNS 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.  Unfor-
     tunately, 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.

BSD                              June 13, 1996                             BSD