usr/src/man/man3socket/ethers.3socket

   1 '\" te
   2 .\" Copyright 1989 AT&T.
   3 .\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" Copyright (C) 2014, Joyent, Inc. All Rights Reserved.
   5 .\" 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.
   6 .\" 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.
   7 .\" 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]
   8 .TH ETHERS 3SOCKET "Aug 9, 2014"
   9 .SH NAME
  10 ethers, ether_ntoa, ether_ntoa_r, ether_aton, ether_aton_r, ether_ntohost, ether_hostton, ether_line \-
  11 Ethernet address mapping operations
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
  16 #include <sys/types.h>
  17 #include <sys/ethernet.h>
  18
  19 \fBchar *\fR\fBether_ntoa\fR(\fBconst struct ether_addr *\fR\fIe\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBchar *\fR\fBether_ntoa_r\fR(\fBconst struct ether_addr *\fR\fIe\fR, \fBchar *\fR\fIs\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBstruct ether_addr *\fR\fBether_aton\fR(\fBconst char *\fR\fIs\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBstruct ether_addr *\fR\fBether_aton_r\fR(\fBconst char *\fR\fIs\fR, \fBstruct ether_addr *\fR\fIe\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBint\fR \fBether_ntohost\fR(\fBchar *\fR\fIhostname\fR, \fBconst struct ether_addr *\fR\fIe\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBint\fR \fBether_hostton\fR(\fBconst char *\fR\fIhostname\fR, \fBstruct ether_addr *\fR\fIe\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBint\fR \fBether_line\fR(\fBconst char *\fR\fIl\fR, \fBstruct ether_addr *\fR\fIe\fR, \fBchar *\fR\fIhostname\fR);
  50 .fi
  51
  52 .SH DESCRIPTION
  53 .LP
  54 These routines are useful for mapping 48 bit Ethernet numbers to their ASCII
  55 representations or their corresponding  host names, and vice versa.
  56 .sp
  57 .LP
  58 The function \fBether_ntoa()\fR converts a 48 bit Ethernet number pointed to by
  59 \fIe\fR to its standard  \fBASCII\fR representation; it returns a pointer to
  60 the  \fBASCII\fR string.  The representation is of the form
  61 \fIx\fR\|:\|\fIx\fR\|:\|\fIx\fR\|:\| \fIx\fR\|:\|\fIx\fR\|:\|\fIx\fR where
  62 \fIx\fR is a hexadecimal number between \fB0\fR and \fBff\fR.  The function
  63 \fBether_aton()\fR converts an \fBASCII\fR string in the standard
  64 representation back to a 48 bit Ethernet number;  the function returns
  65 \fINULL\fR if the string cannot be scanned successfully.
  66 .sp
  67 .LP
  68 The functions \fBether_ntoa()\fR and \fBether_aton()\fR return values in
  69 per-thread buffers, one for each function. A second call to one of these
  70 functions will overwrite the previous value. The functions
  71 \fBether_ntoa_r()\fR and \fBether_aton_r()\fR behave identically to
  72 their non-reentrant versions; however, instead of using a per-thread
  73 buffer, they use caller supplied buffers. It is the callers
  74 responsibility to ensure that the character buffer passed to
  75 \fBether_ntoa_r()\fR is at least \fBETHERADDRSTRL\fR bytes large -- the
  76 minimum size to hold the ASCII representation of a 48 bit Ethernet
  77 number and a null terminator.
  78 .sp
  79 .LP
  80 The function \fBether_ntohost()\fR maps an Ethernet number (pointed to by
  81 \fIe\fR) to its associated hostname.  The string pointed to by hostname must be
  82 long enough to hold the  hostname and a  \fINULL\fR character.  The function
  83 returns zero upon success and non-zero upon failure.  Inversely, the function
  84 \fBether_hostton()\fR maps a hostname string to its corresponding Ethernet
  85 number; the function modifies the  Ethernet number pointed to by \fIe\fR. The
  86 function also returns zero upon  success and non-zero upon failure. In order to
  87 do the mapping, both these functions may lookup one or more of the following
  88 sources: the ethers file, the \fBNIS\fR maps \fBethers.byname\fR and
  89 \fBethers.byaddr\fR and the \fBNIS+\fR table \fBethers\fR. The sources and
  90 their lookup order are specified in the  \fB/etc/nsswitch.conf\fR file. See
  91 \fBnsswitch.conf\fR(4) for details.
  92 .sp
  93 .LP
  94 The function  \fBether_line()\fR scans a line, pointed to by \fIl\fR, and sets
  95 the hostname and the Ethernet number, pointed to by \fIe\fR. The string pointed
  96 to by hostname must be long enough to hold the hostname and a  \fINULL\fR
  97 character.  The function returns zero upon success and non-zero upon failure.
  98 The format of the scanned line is described by  \fBethers\fR(4).
  99 .SH FILES
 100 .ne 2
 101 .na
 102 \fB\fB/etc/ethers\fR\fR
 103 .ad
 104 .RS 22n
 105 Ethernet address to hostname database or domain
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB/etc/nsswitch.conf\fR\fR
 112 .ad
 113 .RS 22n
 114 configuration file for the name service switch
 115 .RE
 116
 117 .SH ATTRIBUTES
 118 .LP
 119 See \fBattributes\fR(5) for descriptions of the following attributes:
 120 .sp
 121
 122 .sp
 123 .TS
 124 box;
 125 c | c
 126 l | l .
 127 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 128 _
 129 MT-Level        MT-Safe
 130 .TE
 131
 132 .SH SEE ALSO
 133 .LP
 134 \fBethers\fR(4), \fBnsswitch.conf\fR(4), \fBattributes\fR(5)