1.\" $NetBSD: linkaddr.3,v 1.2 1995/02/25 06:20:48 cgd 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. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the University of 20.\" California, Berkeley and its contributors. 21.\" 4. Neither the name of the University nor the names of its contributors 22.\" may be used to endorse or promote products derived from this software 23.\" without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 29.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35.\" SUCH DAMAGE. 36.\" 37.\" @(#)linkaddr.3 8.1 (Berkeley) 7/28/93 38.\" 39.Dd July 28, 1993 40.Dt LINK_ADDR 3 41.Os BSD 4.4 42.Sh NAME 43.Nm link_addr , 44.Nm link_ntoa 45.Nd elementary address specification routines for link level access 46.Sh SYNOPSIS 47.Fd #include <sys/types.h> 48.Fd #include <sys/socket.h> 49.Fd #include <net/if_dl.h> 50.Ft void 51.Fn link_addr "const char *addr" "struct sockaddr_dl *sdl" 52.Ft char * 53.Fn link_ntoa "const struct sockaddr_dl *sdl" 54.Sh DESCRIPTION 55The routine 56.Fn link_addr 57interprets character strings representing 58link-level addresses, returning binary information suitable 59for use in system calls. 60The routine 61.Fn link_ntoa 62takes 63a link-level 64address and returns an 65.Tn ASCII 66string representing some of the information present, 67including the link level address itself, and the interface name 68or number, if present. 69This facility is experimental and is 70still subject to change. 71.Pp 72For 73.Fn link_addr , 74the string 75.Fa addr 76may contain 77an optional network interface identifier of the form 78.Dq "name unit-number" , 79suitable for the first argument to 80.Xr ifconfig 4 , 81followed in all cases by a colon and 82an interface address in the form of 83groups of hexadecimal digits 84separated by periods. 85Each group represents a byte of address; 86address bytes are filled left to right from 87low 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 94Thus 95.Li le0:8.0.9.13.d.30 96represents an ethernet address 97to be transmitted on the first Lance ethernet interface. 98.Sh RETURN VALUES 99.Fn link_ntoa 100always returns a null terminated string. 101.Fn link_addr 102has no return value. 103(See 104.Sx BUGS . ) 105.Sh SEE ALSO 106.Xr iso 4 , 107.Sh HISTORY 108The 109.Fn link_addr 110and 111.Fn link_ntoa 112functions appeared in 113.Bx 4.3 Reno . 114.Sh BUGS 115The returned values for link_ntoa 116reside in a static memory area. 117.Pp 118The function 119.Fn link_addr 120should diagnose improperly formed input, and there should be an unambiguous 121way to recognize this. 122.Pp 123If the 124.Va sdl_len 125field of the link socket address 126.Fa sdl 127is 0, 128.Fn link_ntoa 129will not insert a colon before the interface address bytes. 130If this translated address is given to 131.Fn link_addr 132without inserting an initial colon, 133the latter will not interpret it correctly. 134