.\" Copyright (c) 1986, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)ns.3	6.5 (Berkeley) 04/19/91
.\"
.Dd 
.Dt NS 3
.Os BSD 4.3
.Sh NAME
.Nm ns_addr ,
.Nm ns_ntoa
.Nd Xerox
.Tn NS Ns (tm)
address conversion routines
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <netns/ns.h>
.Ft struct ns_addr 
.Fn ns_addr "char *cp"
.Ft char *
.Fn ns_ntoa "struct ns_addr ns"
.Sh DESCRIPTION
The routine
.Fn ns_addr
interprets character strings representing
.Tn XNS
addresses, returning binary information suitable
for use in system calls.
The routine
.Fn ns_ntoa
takes
.Tn XNS
addresses and returns
.Tn ASCII
strings representing the address in a
notation in common use in the Xerox Development Environment:
.Bd -filled -offset indent
<network number>.<host number>.<port number>
.Ed
.Pp
Trailing zero fields are suppressed, and each number is printed in hexadecimal,
in a format suitable for input to 
.Fn ns_addr .
Any fields lacking super-decimal digits will have a
trailing
.Ql H
appended.
.Pp
Unfortunately, no universal standard exists for representing
.Tn XNS
addresses.
An effort has been made to insure that
.Fn ns_addr
be compatible with most formats in common use.
It will first separate an address into 1 to 3 fields using a single delimiter
chosen from
period
.Ql \&. ,
colon
.Ql \&:
or pound-sign
.Ql \&# .
Each field is then examined for byte separators (colon or period).
If there are byte separators, each subfield separated is taken to be
a small hexadecimal number, and the entirety is taken as a network-byte-ordered
quantity to be zero extended in the high-network-order bytes.
Next, the field is inspected for hyphens, in which case
the field is assumed to be a number in decimal notation
with hyphens separating the millenia.
Next, the field is assumed to be a number:
It is interpreted
as hexadecimal if there is a leading
.Ql 0x
(as in C),
a trailing
.Ql H
(as in Mesa), or there are any super-decimal digits present.
It is interpreted as octal is there is a leading
.Ql 0
and there are no super-octal digits.
Otherwise, it is converted as a decimal number.
.Sh RETURN VALUES
None. (See
.Sx BUGS . )
.Sh SEE ALSO
.Xr hosts 5 ,
.Xr networks 5 ,
.Sh HISTORY
The
.Fn ns_addr
and
.Fn ns_toa
functions appeared in 
.Bx 4.3 .
.Sh BUGS
The string returned by
.Fn ns_ntoa
resides in a static memory area.
The function
.Fn ns_addr
should diagnose improperly formed input, and there should be an unambiguous
way to recognize this.