1.\" $NetBSD: ethers.3,v 1.12 2002/09/16 19:25:32 tron 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.Fd #include \*[Lt]sys/types.h\*[Gt] 19.Fd #include \*[Lt]sys/socket.h\*[Gt] 20.Fd #include \*[Lt]net/if.h\*[Gt] 21.Fd #include \*[Lt]net/if_ether.h\*[Gt] 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. It returns a pointer to a static buffer that is reused for 46each call. 47The 48.Fn ether_aton 49converts an ASCII string of the same form and to a structure 50containing the 6 octets of the address. It returns a pointer to a 51static structure that is reused for each call. 52.Pp 53The 54.Fn ether_ntohost 55and 56.Fn ether_hostton 57functions interrogate the data base mapping host names to Ethernet 58addresses, 59.Pa /etc/ethers . 60The 61.Fn ether_ntohost 62function looks up the given Ethernet address and writes the associated 63host name into the character buffer passed. 64The 65.Fn ether_hostton 66function looks up the given host name and writes the associated 67Ethernet address into the structure passed. Both functions return 68zero if they find the requested host name or address, and -1 if not. 69Each call reads 70.Pa /etc/ethers 71from the beginning; if a + appears alone on a line in the file, then 72.Fn ether_hostton 73will consult the 74.Pa ethers.byname 75YP map, and 76.Fn ether_ntohost 77will consult the 78.Pa ethers.byaddr 79YP map. 80.Pp 81The 82.Fn ether_line 83function parses a line from the 84.Pa /etc/ethers 85file and fills in the passed ``struct ether_addr'' and character 86buffer with the Ethernet address and host name on the line. It 87returns zero if the line was successfully parsed and -1 if not. 88.Pp 89The 90.Fa hostname 91buffer for 92.Fn ether_line 93and 94.Fn ether_ntohost 95should be at least 96.Dv MAXHOSTNAMELEN 97+ 1 98characters long, to prevent a buffer overflow during parsing. 99.Sh FILES 100.Bl -tag -width /etc/ethers -compact 101.It Pa /etc/ethers 102.El 103.Sh SEE ALSO 104.Xr ethers 5 105.Sh HISTORY 106The 107.Fn ether_ntoa , 108.Fn ether_aton , 109.Fn ether_ntohost , 110.Fn ether_hostton , 111and 112.Fn ether_line 113functions were adopted from 114.Tn SunOS 115and appeared in 116.Nx 1.0 . 117.Sh BUGS 118The data space used by these functions is static; if future use 119requires the data, it should be copied before any subsequent calls to 120these functions overwrite it. 121