lib/libc/net/iso_addr.3

   1 .\"     $NetBSD: iso_addr.3,v 1.9 2009/04/11 15:32:03 joerg Exp $
   2 .\"
   3 .\" Copyright (c) 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)iso_addr.3  8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd June 4, 1993
  33 .Dt ISO_ADDR 3
  34 .Os
  35 .Sh NAME
  36 .Nm iso_addr ,
  37 .Nm iso_ntoa
  38 .Nd elementary network address conversion routines for Open System Interconnection
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/types.h
  43 .In netiso/iso.h
  44 .Ft struct iso_addr *
  45 .Fn iso_addr "const char *cp"
  46 .Ft char *
  47 .Fn iso_ntoa "struct iso_addr *isoa"
  48 .Sh DESCRIPTION
  49 The routine
  50 .Fn iso_addr
  51 interprets character strings representing
  52 .Tn OSI
  53 addresses, returning binary information suitable
  54 for use in system calls.
  55 The routine
  56 .Fn iso_ntoa
  57 takes
  58 .Tn OSI
  59 addresses and returns
  60 .Tn ASCII
  61 strings representing NSAPs (network service
  62 access points) in a
  63 notation inverse to that accepted by
  64 .Fn iso_addr .
  65 .Pp
  66 Unfortunately, no universal standard exists for representing
  67 .Tn OSI
  68 network addresses.
  69 .Pp
  70 The format employed by
  71 .Fn iso_addr
  72 is a sequence of hexadecimal
  73 .Dq digits
  74 (optionally separated by periods),
  75 of the form:
  76 .Bd -filled -offset indent
  77 \*[Lt]hex digits\*[Gt].\*[Lt]hex digits\*[Gt].\*[Lt]hex digits\*[Gt]
  78 .Ed
  79 .Pp
  80 Each pair of hexadecimal digits represents a byte
  81 with the leading digit indicating the higher-ordered bits.
  82 A period following an even number of bytes has no
  83 effect (but may be used to increase legibility).
  84 A period following an odd number of bytes has the
  85 effect of causing the byte of address being translated
  86 to have its higher order bits filled with zeros.
  87 .Sh RETURN VALUES
  88 .Fn iso_ntoa
  89 always returns a null terminated string.
  90 .Fn iso_addr
  91 always returns a pointer to a struct iso_addr.
  92 (See
  93 .Sx BUGS . )
  94 .Sh SEE ALSO
  95 .Xr iso 4
  96 .Sh HISTORY
  97 The
  98 .Fn iso_addr
  99 and
 100 .Fn iso_ntoa
 101 functions appeared in
 102 .Bx 4.3 Reno .
 103 .Sh BUGS
 104 The returned values
 105 reside in a static memory area.
 106 .Pp
 107 The function
 108 .Fn iso_addr
 109 should diagnose improperly formed input, and there should be an unambiguous
 110 way to recognize this.