ETHERS(3)

💅 ETHERS(3) — ethernet address glow-up central ✨

okay bestie, so this page lives in the Library Functions Manual and it's literally all about the ethers crew — ether_line, ether_aton, ether_aton_r, ether_ntoa, ether_ntoa_r, ether_ntohost, and ether_hostton 🌈 — aka the Ethernet address conversion and lookup routines. MAC addresses but make it fashion 💖

---

🎀 LIBRARY 🎀

Standard C Library, bestie — libc, -lc. She's built in, she's everywhere, she's iconic 👑

---

✨ SYNOPSIS ✨

#include <sys/types.h>
#include <sys/socket.h>
#include <net/ethernet.h>

int
ether_line(const char *l, struct ether_addr *e, char *hostname);

struct ether_addr *
ether_aton(const char *a);

struct ether_addr *
ether_aton_r(const char *a, struct ether_addr *e);

char *
ether_ntoa(const struct ether_addr *n);

char *
ether_ntoa_r(const struct ether_addr *n, char *buf);

int
ether_ntohost(char *hostname, const struct ether_addr *e);

int
ether_hostton(const char *hostname, struct ether_addr *e);

like, seven whole functions, no cap. she's got range 💅

---

🌸 DESCRIPTION 🌸

so these functions all vibe around ethernet addresses using an ether_addr structure, which is defined in the header file <net/ethernet.h>. here she is in all her glory:

/*
 * 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];
};

six bytes of pure main character energy 🦋

ether_line() scans l — an ASCII string in ethers(5) format — and sets e to the ethernet address specified in the string, and h to the hostname. basically it's the parser that takes lines from /etc/ethers and splits them into their component parts. vvv useful for that file specifically 💖

ether_aton() and ether_aton_r() convert the ASCII representation of ethernet addresses into ether_addr structures. and likewise (iykyk), ether_ntoa() and ether_ntoa_r() convert ethernet addresses specified as ether_addr structures into ASCII strings. so it's giving ↔️ bidirectional, obsessed ✨

ether_ntohost() and ether_hostton() map ethernet addresses to their corresponding hostnames as specified in the /etc/ethers database. ether_ntohost() goes from ethernet address ➡️ hostname, and ether_hostton() goes from hostname ➡️ ethernet address. two directions, one slay 💀

---

🔥 RETURN VALUES 🔥

ether_line() returns zero on success and non-zero if it was unable to parse any part of the supplied line l. she returns the extracted ethernet address in the supplied ether_addr structure e and the hostname in the supplied string h 🫶

on success, ether_ntoa() and ether_ntoa_r() return a pointer to a string containing an ASCII representation of an ethernet address. if it's unable to convert the supplied ether_addr structure, it returns a NULL pointer 😭. heads up: ether_ntoa() stores the result in a static buffer, while ether_ntoa_r() stores the result in a user-passed buffer — big difference, don't forget it bestie 👑

likewise, ether_aton() and ether_aton_r() return a pointer to an ether_addr structure on success and a NULL pointer on failure. ether_aton() stores the result in a static buffer; ether_aton_r() stores the result in a user-passed buffer ⭐

ether_ntohost() and ether_hostton() both return zero on success, or non-zero if they were unable to find a match in the /etc/ethers database 🧚

---

💜 NOTES 💜

bestie pls — the user must ensure that the hostname strings passed to ether_line(), ether_ntohost() and ether_hostton() are large enough to contain the returned hostnames. no buffer overflow era, we're not doing that 🙈

---

🌈 NIS INTERACTION 🌈

if /etc/ethers contains a line with a single + in it, then ether_ntohost() and ether_hostton() will attempt to consult the NIS ethers.byname and ethers.byaddr maps in addition to the data in the /etc/ethers file. extra sources, extra slay 💫

---

🦋 SEE ALSO 🦋

• ethers(5)
• yp(8)

go read those too, they're the supporting cast 🎀

---

👑 HISTORY 👑

this particular implementation of the ethers library functions was written for and first appeared in FreeBSD 2.1 — vintage, lowkey iconic 🕰️. the thread-safe function variants (you know, the _r girlies) first appeared in FreeBSD 7.0 ✨

---

💀 BUGS 💀

ether_aton() and ether_ntoa() return values that are stored in static memory areas — which may be overwritten the next time they're called 😭. so like, don't hold onto that pointer and expect it to stay valid, fr fr.

ether_ntoa_r() accepts a character buffer pointer, but not a buffer length. the caller must ensure adequate space is available in the buffer in order to avoid a buffer overflow 🚨. yes that's the dangerous one, be careful, protect your stack bestie 🙏

---

okay that's the whole page! 🍓 this particular rendering came from the Debian flavour, dated October 30, 2007 — oldie but a goodie, and she's still out here converting MAC addresses with main character energy. mwah 💋✨