Debian Codegraph @

upstream/debian-trixie/man3/ether_aton.3

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