man3/ether_aton.3

   1 .\" Copyright 2002 Ian Redfern (redferni@logica.com)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     FreeBSD 4.4 man pages
   8 .\"
   9 .\" Minor additions, aeb, 2013-06-21
  10 .\"
  11 .TH ETHER_ATON 3  2021-03-22 "Linux man-pages (unreleased)"
  12 .SH NAME
  13 ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line,
  14 ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <netinet/ether.h>
  21 .PP
  22 .BI "char *ether_ntoa(const struct ether_addr *" addr );
  23 .BI "struct ether_addr *ether_aton(const char *" asc );
  24 .PP
  25 .BI "int ether_ntohost(char *" hostname ", const struct ether_addr *" addr );
  26 .BI "int ether_hostton(const char *" hostname ", struct ether_addr *" addr );
  27 .PP
  28 .BI "int ether_line(const char *" line ", struct ether_addr *" addr ,
  29 .BI "               char *" hostname );
  30 .PP
  31 /* GNU extensions */
  32 .BI "char *ether_ntoa_r(const struct ether_addr *" addr ", char *" buf );
  33 .PP
  34 .BI "struct ether_addr *ether_aton_r(const char *" asc ,
  35 .BI "                                struct ether_addr *" addr );
  36 .fi
  37 .SH DESCRIPTION
  38 .BR ether_aton ()
  39 converts the 48-bit Ethernet host address
  40 .I asc
  41 from the standard hex-digits-and-colons notation into binary data in
  42 network byte order and returns a pointer to it in a statically
  43 allocated buffer, which subsequent calls will
  44 overwrite.
  45 .BR ether_aton ()
  46 returns NULL if the address is invalid.
  47 .PP
  48 The
  49 .BR ether_ntoa ()
  50 function converts the Ethernet host address
  51 .I addr
  52 given in network byte order to a string in standard
  53 hex-digits-and-colons notation, omitting leading zeros.
  54 The string is returned in a statically allocated buffer,
  55 which subsequent calls will overwrite.
  56 .PP
  57 The
  58 .BR ether_ntohost ()
  59 function maps an Ethernet address to the
  60 corresponding hostname in
  61 .I /etc/ethers
  62 and returns nonzero if it cannot be found.
  63 .PP
  64 The
  65 .BR ether_hostton ()
  66 function maps a hostname to the
  67 corresponding Ethernet address in
  68 .I /etc/ethers
  69 and returns nonzero if it cannot be found.
  70 .PP
  71 The
  72 .BR ether_line ()
  73 function parses a line in
  74 .I /etc/ethers
  75 format (ethernet address followed by whitespace followed by
  76 hostname; \(aq#\(aq introduces a comment) and returns an address
  77 and hostname pair, or nonzero if it cannot be parsed.
  78 The buffer pointed to by
  79 .I hostname
  80 must be sufficiently long, for example, have the same length as
  81 .IR line .
  82 .PP
  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 .PP
  94 The structure
  95 .I ether_addr
  96 is defined in
  97 .I <net/ethernet.h>
  98 as:
  99 .PP
 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 .ad l
 111 .nh
 112 .TS
 113 allbox;
 114 lbx lb lb
 115 l l l.
 116 Interface       Attribute       Value
 117 T{
 118 .BR ether_aton (),
 119 .BR ether_ntoa ()
 120 T}      Thread safety   MT-Unsafe
 121 T{
 122 .BR ether_ntohost (),
 123 .BR ether_hostton (),
 124 .BR ether_line (),
 125 .BR ether_ntoa_r (),
 126 .BR ether_aton_r ()
 127 T}      Thread safety   MT-Safe
 128 .TE
 129 .hy
 130 .ad
 131 .sp 1
 132 .SH STANDARDS
 133 4.3BSD, SunOS.
 134 .SH BUGS
 135 In glibc 2.2.5 and earlier, the implementation of
 136 .BR ether_line ()
 137 .\" The fix was presumably commit c0a0f9a32c8baa6ab93d00eb42d92c02e9e146d7
 138 .\" which was in glibc 2.3
 139 is broken.
 140 .SH SEE ALSO
 141 .BR ethers (5)