---
name: "ethers"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["freebsd", "macos"]
url: "https://new.carta.tech/ethers"
---

# ethers(3)

Ethernet address conversion and lookup routines

## NAME

**ethers**, **ether\_line**, **ether\_aton**, **ether\_ntoa**, **ether\_ntohost**, **ether\_hostton** – Ethernet address conversion and lookup routines

## LIBRARY

Standard C Library (libc, -lc)

## 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*);

*char* *\**\

**ether\_ntoa**(*const struct ether\_addr \*n*);

*int*\

**ether\_ntohost**(*char \*hostname*, *const struct ether\_addr \*e*);

*int*\

**ether\_hostton**(*const char \*hostname*, *struct ether\_addr \*e*);

## DESCRIPTION

These functions operate on ethernet addresses using an *ether\_addr* structure, which is defined in the header file ⟨*netinet/if\_ether.h*⟩:

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

The function **ether\_line**() scans *l*, an ASCII string in [ethers(5)](/ethers/5.md) format and sets *e* to the ethernet address specified in the string and *h* to the hostname. This function is used to parse lines from */etc/ethers* into their component parts.

The **ether\_aton**() function converts an ASCII representation of an ethernet address into an *ether\_addr* structure. Likewise, **ether\_ntoa**() converts an ethernet address specified as an *ether\_addr* structure into an ASCII string.

The **ether\_ntohost**() and **ether\_hostton**() functions map ethernet addresses to their corresponding hostnames as specified in the */etc/ethers* database. **ether\_ntohost**() converts from ethernet address to hostname, and **ether\_hostton**() converts from hostname to ethernet address.

## RETURN VALUES

**ether\_line**() returns zero on success and non-zero if it was unable to parse any part of the supplied line *l*. It returns the extracted ethernet address in the supplied *ether\_addr* structure *e* and the hostname in the supplied string *h*.

On success, **ether\_ntoa**() returns a pointer to a string containing an ASCII representation of an ethernet address. If it is unable to convert the supplied *ether\_addr* structure, it returns a NULL pointer. Likewise, **ether\_aton**() returns a pointer to an *ether\_addr* structure on success and a NULL pointer on failure.

The **ether\_ntohost**() and **ether\_hostton**() functions both return zero on success or non-zero if they were unable to find a match in the */etc/ethers* database.

## NOTES

The user must insure that the hostname strings passed to the **ether\_line**(), **ether\_ntohost**() and **ether\_hostton**() functions are large enough to contain the returned hostnames.

## NIS INTERACTION

If the */etc/ethers* contains a line with a single + in it, the **ether\_ntohost**() and **ether\_hostton**() functions will attempt to consult the NIS *ethers.byname* and *ethers.byaddr* maps in addition to the data in the */etc/ethers* file.

## SEE ALSO

[yp(8)](/yp/8.md), [ethers(5)](/ethers/5.md)

## BUGS

The **ether\_aton**() and **ether\_ntoa**() functions returns values that are stored in static memory areas which may be overwritten the next time they are called.

## HISTORY

This particular implementation of the **ethers** library functions were written for and first appeared in FreeBSD 2.1.