diff --git a/lib/libc/net/Makefile.inc b/lib/libc/net/Makefile.inc index d4ed8b578e1d..4bcd68265e64 100644 --- a/lib/libc/net/Makefile.inc +++ b/lib/libc/net/Makefile.inc @@ -15,12 +15,14 @@ SRCS+= gethostbydns.c gethostbyht.c gethostbynis.c gethostnamadr.c \ # machine-dependent net sources .include "${.CURDIR}/${MACHINE}/net/Makefile.inc" -MAN3+= net/byteorder.3 net/gethostbyname.3 net/getnetent.3 net/getprotoent.3 \ - net/getservent.3 net/inet.3 net/linkaddr.3 net/ns.3 net/rcmd.3 \ - net/resolver.3 +MAN3+= net/byteorder.3 net/ethers.3 net/gethostbyname.3 net/getnetent.3 \ + net/getprotoent.3 net/getservent.3 net/inet.3 net/linkaddr.3 \ + net/ns.3 net/rcmd.3 net/resolver.3 MLINKS+=byteorder.3 htonl.3 byteorder.3 htons.3 byteorder.3 ntohl.3 \ byteorder.3 ntohs.3 +MLINKS+=ethers.3 ether_line.3 ethers.3 ether_aton.3 ethers.3 ether_ntoa.3 \ + ethers.3 ether_ntohost.3 ethers.3 ether_hostton.3 MLINKS+=gethostbyname.3 endhostent.3 gethostbyname.3 gethostbyaddr.3 \ gethostbyname.3 sethostent.3 gethostbyname.3 gethostent.3 \ gethostbyname.3 herror.3 diff --git a/lib/libc/net/ethers.3 b/lib/libc/net/ethers.3 new file mode 100644 index 000000000000..337618e4288b --- /dev/null +++ b/lib/libc/net/ethers.3 @@ -0,0 +1,185 @@ +.\" Copyright (c) 1995 +.\" Bill Paul . All rights reserved. +.\" +.\" 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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. +.\" +.\" $Id$ +.\" +.Dd April 12, 1995 +.Dt ETHERS 3 +.Os FreeBSD 2.1 +.Sh NAME +.Nm ethers , +.Nm ether_line , +.Nm ether_aton , +.Nm ether_ntoa , +.Nm ether_ntohost , +.Nm ether_hostton +.Nd Ethernet address conversion and lookup routines +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn ether_line "char *l" "struct ether_addr *e" "char *hostname" +.Ft struct ether_addr * +.Fn ether_aton "char *a" +.Ft char * +.Fn ether_ntoa "struct ether_addr *n" +.Ft int +.Fn ether_ntohost "char *hostname" "struct ether_addr *e" +.Ft int +.Fn ether_hostton "char *hostname" "struct ether_addr *e" +.Sh DESCRIPTION +These functions operate on ethernet addresses using an +.Ar ether_addr +structure, which is defined in the header file +.Aq Pa netinet/if_ether.h : +.Bd -literal -offset indent +/* + * Structure of a 48-bit Ethernet address. + */ +struct ether_addr { + u_char octet[6]; +}; +.Ed +.Pp +The function +.Fn ether_line +scans +.Ar l , +an +.Tn ASCII +string in +.Xr ethers 5 +format and sets +.Ar e +to the ethernet address specified in the string and +.Ar h +to the hostname. This function is used to parse lines from +.Pa /etc/ethers +into their component parts. +.Pp +The +.Fn ether_aton +function converts an +.Tn ASCII +representation of an ethernet address into an +.Ar ether_addr +structure. Likewise, +.Fn ether_ntoa +converts an ethernet address specified as an +.Ar ether_addr +structure into an +.Tn ASCII +string. +.Pp +The +.Fn ether_ntohost +and +.Fn ether_hostton +functions map ethernet addresses to their corresponding hostnames +as specified in the +.Pa /etc/ethers +database. +.Fn ether_ntohost +converts from ethernet address to hostname, and +.Fn ether_hostton +converts from hostname to ethernet address. +.Sh RETURN VALUES +.Fn ether_line +returns zero on success and non-zero if it was unable to parse +any part of the supplied line +.Ar l . +It returns the extracted ethernet address in the supplied +.Ar ether_addr +structure +.Ar e +and the hostname in the supplied string +.Ar h . +.Pp +On success, +.Fn ether_ntoa +returns a pointer to a string containing an +.Tn ASCII +representation of an ethernet address. If it is unable to convert +the supplied +.Ar ether_addr +structure, it returns a NULL pointer. Likewise, +.Fn ether_aton +returns a pointer to an +.Ar ether_addr +structure on success and a NULL pointer on failure. +.Pp +The +.Fn ether_ntohost +and +.Fn ether_hostton +functions both return zero on success or non-zero if they were +unable to find a match in the +.Pa /etc/ethers +database. +.Sh NOTES +The user must insure that the hostname strings passed to the +the +.Fn ether_line , +.Fn ether_ntohost +and +.Fn ether_hostton +functions are large enough to contain the returned hostnames. +.Sh NIS INTERACTION +If the +.Pa /etc/ethers +contains a line with a single + in it, the +.Fn ether_ntohost +and +.Fn ether_hostton +functions will attempt to consult the NIS +.Pa ethers.byname +and +.Pa ethers.byaddr +maps in addition to the data in the +.Pa /etc/ethers +file. +.Sh SEE ALSO +.Xr ethers 5 , +.Xr yp 8 +.Sh BUGS +.Pp +The +.Fn ether_aton +and +.Fn ether_ntoa +functions returns values that are stored in static memory areas +which may be overwritten the next time they are called. +.Sh HISTORY +This particular implementation of the +.Nm ethers +library functions was written for and first appeared in FreeBSD 2.1.