lib/libc/net/linkaddr.3

   1 .\"     $NetBSD: linkaddr.3,v 1.9 2003/04/16 13:34:42 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Donn Seeley at BSDI.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)linkaddr.3  8.1 (Berkeley) 7/28/93
  34 .\"
  35 .Dd July 28, 1993
  36 .Dt LINK_ADDR 3
  37 .Os
  38 .Sh NAME
  39 .Nm link_addr ,
  40 .Nm link_ntoa
  41 .Nd elementary address specification routines for link level access
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In sys/types.h
  46 .In sys/socket.h
  47 .In net/if_dl.h
  48 .Ft void
  49 .Fn link_addr "const char *addr" "struct sockaddr_dl *sdl"
  50 .Ft char *
  51 .Fn link_ntoa "const struct sockaddr_dl *sdl"
  52 .Sh DESCRIPTION
  53 The routine
  54 .Fn link_addr
  55 interprets character strings representing link-level addresses,
  56 returning binary information suitable for use in system calls.
  57 The routine
  58 .Fn link_ntoa
  59 takes a link-level address and returns an
  60 .Tn ASCII
  61 string representing some of the information present, including the
  62 link level address itself, and the interface name or number, if present.
  63 This facility is experimental and is still subject to change.
  64 .Pp
  65 Prior to a call to
  66 .Fn link_addr ,
  67 .Fa sdl-\*[Gt]sdl_len
  68 must be initialized to the size of the link-level socket structure,
  69 typically
  70 .Fa sizeof(struct sockaddr_dl) .
  71 .Pp
  72 For
  73 .Fn link_addr ,
  74 the string
  75 .Fa addr
  76 may contain
  77 an optional network interface identifier of the form
  78 .Dq "name unit-number" ,
  79 suitable for the first argument to
  80 .Xr ifconfig 8 ,
  81 followed in all cases by a colon and
  82 an interface address in the form of
  83 groups of hexadecimal digits
  84 separated by periods.
  85 Each group represents a byte of address;
  86 address bytes are filled left to right from
  87 low order bytes through high order bytes.
  88 .Pp
  89 .\" A regular expression may make this format clearer:
  90 .\" .Bd -literal -offset indent
  91 .\" ([a-z]+[0-9]+:)?[0-9a-f]+(\e.[0-9a-f]+)*
  92 .\" .Ed
  93 .\" .Pp
  94 Thus
  95 .Li le0:8.0.9.13.d.30
  96 represents an ethernet address
  97 to be transmitted on the first Lance ethernet interface.
  98 .Sh RETURN VALUES
  99 .Fn link_ntoa
 100 always returns a null terminated string.
 101 .Fn link_addr
 102 has no return value (See
 103 .Sx BUGS ) .
 104 .Sh SEE ALSO
 105 .Xr ethers 3 ,
 106 .Xr iso 4
 107 .Sh HISTORY
 108 The
 109 .Fn link_addr
 110 and
 111 .Fn link_ntoa
 112 functions appeared in
 113 .Bx 4.3 Reno .
 114 .Sh BUGS
 115 The returned values for
 116 .Fn link_ntoa
 117 reside in a static memory area.
 118 .Pp
 119 The function
 120 .Fn link_addr
 121 should diagnose improperly formed input, and there should be an unambiguous
 122 way to recognize this.
 123 .Pp
 124 If the
 125 .Va sdl_len
 126 field of the link socket address
 127 .Fa sdl
 128 is 0,
 129 .Fn link_ntoa
 130 will not insert a colon before the interface address bytes.
 131 If this translated address is given to
 132 .Fn link_addr
 133 without inserting an initial colon,
 134 the latter will not interpret it correctly.