ifreq_linux.go

     1  // Copyright 2021 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  //go:build linux
     6  // +build linux
     7  
     8  package unix
     9  
    10  import (
    11  	"bytes"
    12  	"unsafe"
    13  )
    14  
    15  // Helpers for dealing with ifreq since it contains a union and thus requires a
    16  // lot of unsafe.Pointer casts to use properly.
    17  
    18  // An Ifreq is a type-safe wrapper around the raw ifreq struct. An Ifreq
    19  // contains an interface name and a union of arbitrary data which can be
    20  // accessed using the Ifreq's methods. To create an Ifreq, use the NewIfreq
    21  // function.
    22  //
    23  // Use the Name method to access the stored interface name. The union data
    24  // fields can be get and set using the following methods:
    25  //   - Uint16/SetUint16: flags
    26  //   - Uint32/SetUint32: ifindex, metric, mtu
    27  type Ifreq struct{ raw ifreq }
    28  
    29  // NewIfreq creates an Ifreq with the input network interface name after
    30  // validating the name does not exceed IFNAMSIZ-1 (trailing NULL required)
    31  // bytes.
    32  func NewIfreq(name string) (*Ifreq, error) {
    33  	// Leave room for terminating NULL byte.
    34  	if len(name) >= IFNAMSIZ {
    35  		return nil, EINVAL
    36  	}
    37  
    38  	var ifr ifreq
    39  	copy(ifr.Ifrn[:], name)
    40  
    41  	return &Ifreq{raw: ifr}, nil
    42  }
    43  
    44  // TODO(mdlayher): get/set methods for hardware address sockaddr, char array, etc.
    45  
    46  // Name returns the interface name associated with the Ifreq.
    47  func (ifr *Ifreq) Name() string {
    48  	// BytePtrToString requires a NULL terminator or the program may crash. If
    49  	// one is not present, just return the empty string.
    50  	if !bytes.Contains(ifr.raw.Ifrn[:], []byte{0x00}) {
    51  		return ""
    52  	}
    53  
    54  	return BytePtrToString(&ifr.raw.Ifrn[0])
    55  }
    56  
    57  // According to netdevice(7), only AF_INET addresses are returned for numerous
    58  // sockaddr ioctls. For convenience, we expose these as Inet4Addr since the Port
    59  // field and other data is always empty.
    60  
    61  // Inet4Addr returns the Ifreq union data from an embedded sockaddr as a C
    62  // in_addr/Go []byte (4-byte IPv4 address) value. If the sockaddr family is not
    63  // AF_INET, an error is returned.
    64  func (ifr *Ifreq) Inet4Addr() ([]byte, error) {
    65  	raw := *(*RawSockaddrInet4)(unsafe.Pointer(&ifr.raw.Ifru[:SizeofSockaddrInet4][0]))
    66  	if raw.Family != AF_INET {
    67  		// Cannot safely interpret raw.Addr bytes as an IPv4 address.
    68  		return nil, EINVAL
    69  	}
    70  
    71  	return raw.Addr[:], nil
    72  }
    73  
    74  // SetInet4Addr sets a C in_addr/Go []byte (4-byte IPv4 address) value in an
    75  // embedded sockaddr within the Ifreq's union data. v must be 4 bytes in length
    76  // or an error will be returned.
    77  func (ifr *Ifreq) SetInet4Addr(v []byte) error {
    78  	if len(v) != 4 {
    79  		return EINVAL
    80  	}
    81  
    82  	var addr [4]byte
    83  	copy(addr[:], v)
    84  
    85  	ifr.clear()
    86  	*(*RawSockaddrInet4)(
    87  		unsafe.Pointer(&ifr.raw.Ifru[:SizeofSockaddrInet4][0]),
    88  	) = RawSockaddrInet4{
    89  		// Always set IP family as ioctls would require it anyway.
    90  		Family: AF_INET,
    91  		Addr:   addr,
    92  	}
    93  
    94  	return nil
    95  }
    96  
    97  // Uint16 returns the Ifreq union data as a C short/Go uint16 value.
    98  func (ifr *Ifreq) Uint16() uint16 {
    99  	return *(*uint16)(unsafe.Pointer(&ifr.raw.Ifru[:2][0]))
   100  }
   101  
   102  // SetUint16 sets a C short/Go uint16 value as the Ifreq's union data.
   103  func (ifr *Ifreq) SetUint16(v uint16) {
   104  	ifr.clear()
   105  	*(*uint16)(unsafe.Pointer(&ifr.raw.Ifru[:2][0])) = v
   106  }
   107  
   108  // Uint32 returns the Ifreq union data as a C int/Go uint32 value.
   109  func (ifr *Ifreq) Uint32() uint32 {
   110  	return *(*uint32)(unsafe.Pointer(&ifr.raw.Ifru[:4][0]))
   111  }
   112  
   113  // SetUint32 sets a C int/Go uint32 value as the Ifreq's union data.
   114  func (ifr *Ifreq) SetUint32(v uint32) {
   115  	ifr.clear()
   116  	*(*uint32)(unsafe.Pointer(&ifr.raw.Ifru[:4][0])) = v
   117  }
   118  
   119  // clear zeroes the ifreq's union field to prevent trailing garbage data from
   120  // being sent to the kernel if an ifreq is reused.
   121  func (ifr *Ifreq) clear() {
   122  	for i := range ifr.raw.Ifru {
   123  		ifr.raw.Ifru[i] = 0
   124  	}
   125  }
   126  
   127  // TODO(mdlayher): export as IfreqData? For now we can provide helpers such as
   128  // IoctlGetEthtoolDrvinfo which use these APIs under the hood.
   129  
   130  // An ifreqData is an Ifreq which carries pointer data. To produce an ifreqData,
   131  // use the Ifreq.withData method.
   132  type ifreqData struct {
   133  	name [IFNAMSIZ]byte
   134  	// A type separate from ifreq is required in order to comply with the
   135  	// unsafe.Pointer rules since the "pointer-ness" of data would not be
   136  	// preserved if it were cast into the byte array of a raw ifreq.
   137  	data unsafe.Pointer
   138  	// Pad to the same size as ifreq.
   139  	_ [len(ifreq{}.Ifru) - SizeofPtr]byte
   140  }
   141  
   142  // withData produces an ifreqData with the pointer p set for ioctls which require
   143  // arbitrary pointer data.
   144  func (ifr Ifreq) withData(p unsafe.Pointer) ifreqData {
   145  	return ifreqData{
   146  		name: ifr.raw.Ifrn,
   147  		data: p,
   148  	}
   149  }
   150
View as plain text