Debian Codegraph @

upstream/debian-unstable/man3/ether_aton.3

raw
1 '\" t
2 .\" Copyright 2002, Ian Redfern <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH ether_aton 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line,
10 ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <netinet/ether.h>
17 .P
18 .BI "char *ether_ntoa(const struct ether_addr *" addr );
19 .BI "struct ether_addr *ether_aton(const char *" asc );
20 .P
21 .BI "int ether_ntohost(char *" hostname ", const struct ether_addr *" addr );
22 .BI "int ether_hostton(const char *" hostname ", struct ether_addr *" addr );
23 .P
24 .BI "int ether_line(const char *" line ", struct ether_addr *" addr ,
25 .BI " char *" hostname );
26 .P
27 /* GNU extensions */
28 .BI "char *ether_ntoa_r(const struct ether_addr *" addr ", char *" buf );
29 .P
30 .BI "struct ether_addr *ether_aton_r(const char *" asc ,
31 .BI " struct ether_addr *" addr );
32 .fi
33 .SH DESCRIPTION
34 .BR ether_aton ()
35 converts the 48-bit Ethernet host address
36 .I asc
37 from the standard hex-digits-and-colons notation into binary data in
38 network byte order and returns a pointer to it in a statically
39 allocated buffer, which subsequent calls will
40 overwrite.
41 .BR ether_aton ()
42 returns NULL if the address is invalid.
43 .P
44 The
45 .BR ether_ntoa ()
46 function converts the Ethernet host address
47 .I addr
48 given in network byte order to a string in standard
49 hex-digits-and-colons notation, omitting leading zeros.
50 The string is returned in a statically allocated buffer,
51 which subsequent calls will overwrite.
52 .P
53 The
54 .BR ether_ntohost ()
55 function maps an Ethernet address to the
56 corresponding hostname in
57 .I /etc/ethers
58 and returns nonzero if it cannot be found.
59 .P
60 The
61 .BR ether_hostton ()
62 function maps a hostname to the
63 corresponding Ethernet address in
64 .I /etc/ethers
65 and returns nonzero if it cannot be found.
66 .P
67 The
68 .BR ether_line ()
69 function parses a line in
70 .I /etc/ethers
71 format
72 (ethernet address followed by whitespace followed by hostname;
73 \[aq]#\[aq] introduces a comment)
74 and returns an address and hostname pair,
75 or nonzero if it cannot be parsed.
76 The buffer pointed to by
77 .I hostname
78 must be sufficiently long
79 \[em]for example,
80 have the same length as
81 .IR line \[em].
82 .P
83 The functions
84 .BR ether_ntoa_r ()
85 and
86 .BR ether_aton_r ()
87 are reentrant
88 thread-safe versions of
89 .BR ether_ntoa ()
90 and
91 .BR ether_aton ()
92 respectively, and do not use static buffers.
93 .P
94 The structure
95 .I ether_addr
96 is defined in
97 .I <net/ethernet.h>
98 as:
99 .P
100 .in +4n
101 .EX
102 struct ether_addr {
103 uint8_t ether_addr_octet[6];
104 }
105 .EE
106 .in
107 .SH ATTRIBUTES
108 For an explanation of the terms used in this section, see
109 .BR attributes (7).
110 .TS
111 allbox;
112 lbx lb lb
113 l l l.
114 Interface Attribute Value
115 T{
116 .na
117 .nh
118 .BR ether_aton (),
119 .BR ether_ntoa ()
120 T} Thread safety MT-Unsafe
121 T{
122 .na
123 .nh
124 .BR ether_ntohost (),
125 .BR ether_hostton (),
126 .BR ether_line (),
127 .BR ether_ntoa_r (),
128 .BR ether_aton_r ()
129 T} Thread safety MT-Safe
130 .TE
131 .SH STANDARDS
132 None.
133 .SH HISTORY
134 4.3BSD, SunOS.
135 .SH BUGS
136 In glibc 2.2.5 and earlier, the implementation of
137 .BR ether_line ()
138 .\" The fix was presumably commit c0a0f9a32c8baa6ab93d00eb42d92c02e9e146d7
139 .\" which was in glibc 2.3
140 is broken.
141 .SH SEE ALSO
142 .BR ethers (5)