1.\" $NetBSD: ethers.3,v 1.15 2017/10/30 15:46:38 wiz Exp $ 2.\" 3.\" Written by roland@frob.com. Public domain. 4.\" 5.Dd November 2, 1997 6.Dt ETHERS 3 7.Os 8.Sh NAME 9.Nm ether_ntoa , 10.Nm ether_aton , 11.Nm ether_ntohost , 12.Nm ether_hostton , 13.Nm ether_line 14.Nd get ethers entry 15.Sh LIBRARY 16.Lb libc 17.Sh SYNOPSIS 18.In sys/types.h 19.In sys/socket.h 20.In net/if.h 21.In net/if_ether.h 22.Ft char * 23.Fn ether_ntoa "const struct ether_addr *e" 24.Ft struct ether_addr * 25.Fn ether_aton "const char *s" 26.Ft int 27.Fn ether_ntohost "char *hostname" "const struct ether_addr *e" 28.Ft int 29.Fn ether_hostton "const char *hostname" "struct ether_addr *e" 30.Ft int 31.Fn ether_line "const char *line" "struct ether_addr *e" "char *hostname" 32.Sh DESCRIPTION 33Ethernet addresses are represented by the 34following structure: 35.Bd -literal -offset indent 36struct ether_addr { 37 u_char ether_addr_octet[6]; 38}; 39.Ed 40.Pp 41The 42.Fn ether_ntoa 43function converts this structure into an ASCII string of the form 44``xx:xx:xx:xx:xx:xx'', consisting of 6 hexadecimal numbers separated 45by colons. 46It returns a pointer to a static buffer that is reused for 47each call. 48The 49.Fn ether_aton 50converts an ASCII string of the same form and to a structure 51containing the 6 octets of the address. 52It returns a pointer to a 53static structure that is reused for each call. 54.Pp 55The 56.Fn ether_ntohost 57and 58.Fn ether_hostton 59functions interrogate the data base mapping host names to Ethernet 60addresses, 61.Pa /etc/ethers . 62The 63.Fn ether_ntohost 64function looks up the given Ethernet address and writes the associated 65host name into the character buffer passed. 66The 67.Fn ether_hostton 68function looks up the given host name and writes the associated 69Ethernet address into the structure passed. 70Both functions return 71zero if they find the requested host name or address, and -1 if not. 72Each call reads 73.Pa /etc/ethers 74from the beginning; if a + appears alone on a line in the file, then 75.Fn ether_hostton 76will consult the 77.Pa ethers.byname 78YP map, and 79.Fn ether_ntohost 80will consult the 81.Pa ethers.byaddr 82YP map. 83.Pp 84The 85.Fn ether_line 86function parses a line from the 87.Pa /etc/ethers 88file and fills in the passed ``struct ether_addr'' and character 89buffer with the Ethernet address and host name on the line. 90It returns zero if the line was successfully parsed and -1 if not. 91.Pp 92The 93.Fa hostname 94buffer for 95.Fn ether_line 96and 97.Fn ether_ntohost 98should be at least 99.Dv MAXHOSTNAMELEN 100+ 1 101characters long, to prevent a buffer overflow during parsing. 102.Sh FILES 103.Bl -tag -width /etc/ethers -compact 104.It Pa /etc/ethers 105.El 106.Sh SEE ALSO 107.Xr ethers 5 108.Sh HISTORY 109The 110.Fn ether_ntoa , 111.Fn ether_aton , 112.Fn ether_ntohost , 113.Fn ether_hostton , 114and 115.Fn ether_line 116functions were adopted from SunOS and appeared in 117.Nx 1.0 . 118.Sh BUGS 119The data space used by these functions is static; if future use 120requires the data, it should be copied before any subsequent calls to 121these functions overwrite it. 122