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.Dd May 9, 2025 32.Dt LINK_ADDR 3 33.Os 34.Sh NAME 35.Nm link_addr , 36.Nm link_ntoa , 37.Nm link_ntoa_r 38.Nd elementary address specification routines for link level access 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In sys/types.h 43.In sys/socket.h 44.In net/if_dl.h 45.Ft int 46.Fn link_addr "const char *addr" "struct sockaddr_dl *sdl" 47.Ft char * 48.Fn link_ntoa "const struct sockaddr_dl *sdl" 49.Ft int 50.Fn link_ntoa_r "const struct sockaddr_dl *sdl" "char *obuf" "size_t *buflen" 51.Sh DESCRIPTION 52The routine 53.Fn link_addr 54parses a character string 55.Fa addr 56representing a link-level address, 57and stores the resulting address in the structure pointed to by 58.Fa sdl . 59A link-level address consists of an optional interface name, followed by 60a colon (which is required in all cases), followed by an address 61consisting of either a string of hexadecimal digits, or a series of 62hexadecimal octets separated by one of the characters 63.Sq "." , 64.Sq ":" , 65or 66.Sq - . 67.Pp 68The routine 69.Fn link_ntoa 70takes 71a link-level 72address and returns an 73.Tn ASCII 74string representing some of the information present, 75including the link level address itself, and the interface name 76or number, if present. 77The returned string is stored in a static buffer. 78This facility is experimental and is 79still subject to change. 80.Pp 81The routine 82.Fn link_ntoa_r 83behaves like 84.Fn link_ntoa , 85except the string is placed in the provided buffer instead of a static 86buffer. 87The caller should initialize 88.Fa buflen 89to the number of bytes available in 90.Fa obuf . 91On return, 92.Fa buflen 93is set to the actual number of bytes required for the output buffer, 94including the NUL terminator. 95If 96.Fa obuf 97is NULL, then 98.Fa buflen 99is set as described, but nothing is written. 100This may be used to determine the required length of the buffer before 101calling 102.Fn link_ntoa_r 103a second time. 104.Pp 105For 106.Fn link_addr , 107the string 108.Fa addr 109may contain 110an optional network interface identifier of the form 111.Dq "name unit-number" , 112suitable for the first argument to 113.Xr ifconfig 8 , 114followed in all cases by a colon and 115an interface address in the form of 116groups of hexadecimal digits 117separated by periods. 118Each group represents a byte of address; 119address bytes are filled left to right from 120low order bytes through high order bytes. 121.Pp 122.\" A regular expression may make this format clearer: 123.\" .Bd -literal -offset indent 124.\" ([a-z]+[0-9]+:)?[0-9a-f]+(\e.[0-9a-f]+)* 125.\" .Ed 126.\" .Pp 127Thus 128.Li le0:8.0.9.13.d.30 129represents an ethernet address 130to be transmitted on the first Lance ethernet interface. 131.Sh RETURN VALUES 132The 133.Fn link_ntoa 134function 135always returns a null terminated string. 136.Pp 137The 138.Fn link_ntoa_r 139function returns 0 on success, or -1 if the provided buffer was not 140large enough; in the latter case, the contents of the buffer are 141indeterminate, but a trailing NUL will always be written if the buffer 142was at least one byte in size. 143.Pp 144The 145.Fn link_addr 146function returns 0 on success. 147If the address did not appear to be a valid link-level address, -1 is 148returned and 149.Va errno 150is set to indicate the error. 151.Sh SEE ALSO 152.Xr getnameinfo 3 153.Sh HISTORY 154The 155.Fn link_addr 156and 157.Fn link_ntoa 158functions appeared in 159.Bx 4.3 Reno . 160The 161.Fn link_ntoa_r 162function appeared in 163.Fx 15.0 . 164.Sh BUGS 165The returned values for link_ntoa 166reside in a static memory area. 167.Pp 168If the 169.Va sdl_len 170field of the link socket address 171.Fa sdl 172is 0, 173.Fn link_ntoa 174will not insert a colon before the interface address bytes. 175If this translated address is given to 176.Fn link_addr 177without inserting an initial colon, 178the latter will not interpret it correctly. 179