diff options
Diffstat (limited to 'cpukit/libnetworking/libc/ethers.3')
| -rw-r--r-- | cpukit/libnetworking/libc/ethers.3 | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/cpukit/libnetworking/libc/ethers.3 b/cpukit/libnetworking/libc/ethers.3 new file mode 100644 index 0000000000..afea48320a --- /dev/null +++ b/cpukit/libnetworking/libc/ethers.3 @@ -0,0 +1,193 @@ +.\" Copyright (c) 1995 +.\" Bill Paul <wpaul@ctr.columbia.edu>. 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 <sys/types.h> +.Fd #include <sys/socket.h> +.Fd #include <net/ethernet.h> +.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 +/* + * The number of bytes in an ethernet (MAC) address. + */ +#define ETHER_ADDR_LEN 6 + +/* + * Structure of a 48-bit Ethernet address. + */ +struct ether_addr { + u_char octet[ETHER_ADDR_LEN]; +}; +.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 +.Dv NULL +pointer. Likewise, +.Fn ether_aton +returns a pointer to an +.Ar ether_addr +structure on success and a +.Dv 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 yp 4 , +.Xr ethers 5 +.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 were written for and first appeared in +.Fx 2.1 . |