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