'\" te
.\" Copyright 1989 AT&T.
.\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ethers 3SOCKET "5 Apr 2004" "SunOS 5.11" "Sockets Library Functions"
.SH NAME
ethers, ether_ntoa, ether_aton, ether_ntohost, ether_hostton, ether_line \-
Ethernet address mapping operations
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
#include <sys/types.h>
#include <sys/ethernet.h>

\fBchar *\fR\fBether_ntoa\fR(\fBconst struct ether_addr *\fR\fIe\fR);
.fi

.LP
.nf
\fBstruct ether_addr *\fR\fBether_aton\fR(\fBconst char *\fR\fIs\fR);
.fi

.LP
.nf
\fBint\fR \fBether_ntohost\fR(\fBchar *\fR\fIhostname\fR, \fBconst struct ether_addr *\fR\fIe\fR);
.fi

.LP
.nf
\fBint\fR \fBether_hostton\fR(\fBconst char *\fR\fIhostname\fR, \fBstruct ether_addr *\fR\fIe\fR);
.fi

.LP
.nf
\fBint\fR \fBether_line\fR(\fBconst char *\fR\fIl\fR, \fBstruct ether_addr *\fR\fIe\fR, \fBchar *\fR\fIhostname\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These routines are useful for mapping 48 bit Ethernet numbers to their ASCII
representations or their corresponding  host names, and vice versa.
.sp
.LP
The function \fBether_ntoa()\fR converts a 48 bit Ethernet number pointed to by
\fIe\fR to its standard  \fBASCII\fR representation; it returns a pointer to
the  \fBASCII\fR string.  The representation is of the form
\fIx\fR\|:\|\fIx\fR\|:\|\fIx\fR\|:\| \fIx\fR\|:\|\fIx\fR\|:\|\fIx\fR where
\fIx\fR is a hexadecimal number between \fB0\fR and \fBff\fR.  The function
\fBether_aton()\fR converts an \fBASCII\fR string in the standard
representation back to a 48 bit Ethernet number;  the function returns
\fINULL\fR if the string cannot be scanned successfully.
.sp
.LP
The function \fBether_ntohost()\fR maps an Ethernet number (pointed to by
\fIe\fR) to its associated hostname.  The string pointed to by hostname must be
long enough to hold the  hostname and a  \fINULL\fR character.  The function
returns zero upon success and non-zero upon failure.  Inversely, the function
\fBether_hostton()\fR maps a hostname string to its corresponding Ethernet
number; the function modifies the  Ethernet number pointed to by \fIe\fR. The
function also returns zero upon  success and non-zero upon failure. In order to
do the mapping, both these functions may lookup one or more of the following
sources: the ethers file, the \fBNIS\fR maps \fBethers.byname\fR and
\fBethers.byaddr\fR and the \fBNIS+\fR table \fBethers\fR. The sources and
their lookup order are specified in the  \fB/etc/nsswitch.conf\fR file. See
\fBnsswitch.conf\fR(4) for details.
.sp
.LP
The function  \fBether_line()\fR scans a line, pointed to by \fIl\fR, and sets
the hostname and the Ethernet number, pointed to by \fIe\fR. The string pointed
to by hostname must be long enough to hold the hostname and a  \fINULL\fR
character.  The function returns zero upon success and non-zero upon failure.
The format of the scanned line is described by  \fBethers\fR(4).
.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/etc/ethers\fR\fR
.ad
.RS 22n
.rt  
Ethernet address to hostname database or domain
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/nsswitch.conf\fR\fR
.ad
.RS 22n
.rt  
configuration file for the name service switch
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBethers\fR(4), \fBnsswitch.conf\fR(4), \fBattributes\fR(5)