[apple/libc.git] / net / linkaddr.3

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