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. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" From: @(#)linkaddr.3 8.1 (Berkeley) 7/28/93 32.\" 33.Dd February 28, 2007 34.Dt LINK_ADDR 3 35.Os 36.Sh NAME 37.Nm link_addr , 38.Nm link_ntoa 39.Nd elementary address specification routines for link level access 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/types.h 44.In sys/socket.h 45.In net/if_dl.h 46.Ft void 47.Fn link_addr "const char *addr" "struct sockaddr_dl *sdl" 48.Ft char * 49.Fn link_ntoa "const struct sockaddr_dl *sdl" 50.Sh DESCRIPTION 51The routine 52.Fn link_addr 53interprets character strings representing 54link-level addresses, returning binary information suitable 55for use in system calls. 56The routine 57.Fn link_ntoa 58takes 59a link-level 60address and returns an 61.Tn ASCII 62string representing some of the information present, 63including the link level address itself, and the interface name 64or number, if present. 65This facility is experimental and is 66still subject to change. 67.Pp 68For 69.Fn link_addr , 70the string 71.Fa addr 72may contain 73an optional network interface identifier of the form 74.Dq "name unit-number" , 75suitable for the first argument to 76.Xr ifconfig 8 , 77followed in all cases by a colon and 78an interface address in the form of 79groups of hexadecimal digits 80separated by periods. 81Each group represents a byte of address; 82address bytes are filled left to right from 83low order bytes through high order bytes. 84.Pp 85.\" A regular expression may make this format clearer: 86.\" .Bd -literal -offset indent 87.\" ([a-z]+[0-9]+:)?[0-9a-f]+(\e.[0-9a-f]+)* 88.\" .Ed 89.\" .Pp 90Thus 91.Li le0:8.0.9.13.d.30 92represents an ethernet address 93to be transmitted on the first Lance ethernet interface. 94.Sh RETURN VALUES 95The 96.Fn link_ntoa 97function 98always returns a null terminated string. 99The 100.Fn link_addr 101function 102has no return value. 103(See 104.Sx BUGS . ) 105.Sh SEE ALSO 106.Xr getnameinfo 3 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