kernel: Remove some old ISA only drivers.
[dragonfly.git] / lib / libc / net / linkaddr.3
CommitLineData
984263bc
MD
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.
984263bc
MD
15.\" 4. 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
12b71966 32.\" $FreeBSD: src/lib/libc/net/linkaddr.3,v 1.16 2007/02/28 21:18:38 bms Exp $
984263bc 33.\"
12b71966 34.Dd February 28, 2007
984263bc
MD
35.Dt LINK_ADDR 3
36.Os
37.Sh NAME
38.Nm link_addr ,
39.Nm link_ntoa
40.Nd elementary address specification routines for link level access
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/types.h
45.In sys/socket.h
46.In net/if_dl.h
47.Ft void
48.Fn link_addr "const char *addr" "struct sockaddr_dl *sdl"
49.Ft char *
50.Fn link_ntoa "const struct sockaddr_dl *sdl"
51.Sh DESCRIPTION
52The routine
53.Fn link_addr
54interprets character strings representing
55link-level addresses, returning binary information suitable
56for use in system calls.
57The routine
58.Fn link_ntoa
59takes
60a link-level
61address and returns an
62.Tn ASCII
63string representing some of the information present,
64including the link level address itself, and the interface name
65or number, if present.
66This facility is experimental and is
67still subject to change.
68.Pp
69For
70.Fn link_addr ,
71the string
72.Fa addr
73may contain
74an optional network interface identifier of the form
75.Dq "name unit-number" ,
76suitable for the first argument to
77.Xr ifconfig 8 ,
78followed in all cases by a colon and
79an interface address in the form of
80groups of hexadecimal digits
81separated by periods.
82Each group represents a byte of address;
83address bytes are filled left to right from
84low order bytes through high order bytes.
85.Pp
86.\" A regular expression may make this format clearer:
87.\" .Bd -literal -offset indent
88.\" ([a-z]+[0-9]+:)?[0-9a-f]+(\e.[0-9a-f]+)*
89.\" .Ed
90.\" .Pp
91Thus
ad9f8794 92.Li lnc0:8.0.9.13.d.30
984263bc
MD
93represents an ethernet address
94to be transmitted on the first Lance ethernet interface.
984263bc 95.Sh RETURN VALUES
12b71966 96The
984263bc 97.Fn link_ntoa
12b71966 98function
984263bc 99always returns a null terminated string.
12b71966 100The
984263bc 101.Fn link_addr
12b71966 102function
984263bc
MD
103has no return value.
104(See
105.Sx BUGS . )
106.Sh SEE ALSO
12b71966 107.Xr getnameinfo 3
984263bc
MD
108.Sh HISTORY
109The
110.Fn link_addr
111and
112.Fn link_ntoa
113functions appeared in
12b71966 114.Bx 4.3 Reno .
984263bc 115.Sh BUGS
3efc72a7
SW
116The returned values for
117.Fn link_ntoa
984263bc
MD
118reside in a static memory area.
119.Pp
120The function
121.Fn link_addr
122should diagnose improperly formed input, and there should be an unambiguous
123way to recognize this.
124.Pp
125If the
126.Va sdl_len
127field of the link socket address
128.Fa sdl
129is 0,
130.Fn link_ntoa
131will not insert a colon before the interface address bytes.
132If this translated address is given to
133.Fn link_addr
134without inserting an initial colon,
135the latter will not interpret it correctly.