unix: export Ifreq and add IoctlIfreq function

This CL expands upon CL 340369 by exporting the Ifreq type along with methods
for setting and getting data to/from the ifreq union in a type-safe way.
ifreqData remains unexported as we can keep adding helpers similar to the
IoctlGetEthtoolDrvinfo to expose those operations in a less error-prone way.

A test is also added to verify interface index data using IoctlIfreq against
the modern rtnetlink API used by the standard library.

Change-Id: Ic6980cbcd3792cc341cd614061cce32fa1f851e7
Reviewed-on: https://go-review.googlesource.com/c/sys/+/340370
Trust: Matt Layher <mdlayher@gmail.com>
Run-TryBot: Matt Layher <mdlayher@gmail.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

unix/ifreq_linux.go

@@ -7,15 +7,29 @@
 
 package unix
 
-import "unsafe"
+import (
+	"bytes"
+	"unsafe"
+)
 
 // Helpers for dealing with ifreq since it contains a union and thus requires a
 // lot of unsafe.Pointer casts to use properly.
 
-// newIfreq creates an ifreq with the input network interface name after
+// An Ifreq is a type-safe wrapper around the raw ifreq struct. An Ifreq
+// contains an interface name and a union of arbitrary data which can be
+// accessed using the Ifreq's methods. To create an Ifreq, use the NewIfreq
+// function.
+//
+// Use the Name method to access the stored interface name. The union data
+// fields can be get and set using the following methods:
+//   - Uint16/SetUint16: flags
+//   - Uint32/SetUint32: ifindex, metric, mtu
+type Ifreq struct{ raw ifreq }
+
+// NewIfreq creates an Ifreq with the input network interface name after
 // validating the name does not exceed IFNAMSIZ-1 (trailing NULL required)
 // bytes.
-func newIfreq(name string) (*ifreq, error) {
+func NewIfreq(name string) (*Ifreq, error) {
 	// Leave room for terminating NULL byte.
 	if len(name) >= IFNAMSIZ {
 		return nil, EINVAL
@@ -24,25 +38,72 @@ func newIfreq(name string) (*ifreq, error) {
 	var ifr ifreq
 	copy(ifr.Ifrn[:], name)
 
-	return &ifr, nil
+	return &Ifreq{raw: ifr}, nil
 }
 
-// An ifreqData is an ifreq but with a typed unsafe.Pointer field for data in
-// the union. This is required in order to comply with the unsafe.Pointer rules
-// since the "pointer-ness" of data would not be preserved if it were cast into
-// the byte array of a raw ifreq.
+// TODO(mdlayher): get/set methods for sockaddr, char array, etc.
+
+// Name returns the interface name associated with the Ifreq.
+func (ifr *Ifreq) Name() string {
+	// BytePtrToString requires a NULL terminator or the program may crash. If
+	// one is not present, just return the empty string.
+	if !bytes.Contains(ifr.raw.Ifrn[:], []byte{0x00}) {
+		return ""
+	}
+
+	return BytePtrToString(&ifr.raw.Ifrn[0])
+}
+
+// Uint16 returns the Ifreq union data as a C short/Go uint16 value.
+func (ifr *Ifreq) Uint16() uint16 {
+	return *(*uint16)(unsafe.Pointer(&ifr.raw.Ifru[:2][0]))
+}
+
+// SetUint16 sets a C short/Go uint16 value as the Ifreq's union data.
+func (ifr *Ifreq) SetUint16(v uint16) {
+	ifr.clear()
+	*(*uint16)(unsafe.Pointer(&ifr.raw.Ifru[:2][0])) = v
+}
+
+// Uint32 returns the Ifreq union data as a C int/Go uint32 value.
+func (ifr *Ifreq) Uint32() uint32 {
+	return *(*uint32)(unsafe.Pointer(&ifr.raw.Ifru[:4][0]))
+}
+
+// SetUint32 sets a C int/Go uint32 value as the Ifreq's union data.
+func (ifr *Ifreq) SetUint32(v uint32) {
+	ifr.clear()
+	*(*uint32)(unsafe.Pointer(&ifr.raw.Ifru[:4][0])) = v
+}
+
+// clear zeroes the ifreq's union field to prevent trailing garbage data from
+// being sent to the kernel if an ifreq is reused.
+func (ifr *Ifreq) clear() {
+	for i := range ifr.raw.Ifru {
+		ifr.raw.Ifru[i] = 0
+	}
+}
+
+// TODO(mdlayher): export as IfreqData? For now we can provide helpers such as
+// IoctlGetEthtoolDrvinfo which use these APIs under the hood.
+
+// An ifreqData is an Ifreq which carries pointer data. To produce an ifreqData,
+// use the Ifreq.withData method.
 type ifreqData struct {
 	name [IFNAMSIZ]byte
+	// A type separate from ifreq is required in order to comply with the
+	// unsafe.Pointer rules since the "pointer-ness" of data would not be
+	// preserved if it were cast into the byte array of a raw ifreq.
 	data unsafe.Pointer
 	// Pad to the same size as ifreq.
 	_ [len(ifreq{}.Ifru) - SizeofPtr]byte
 }
 
-// SetData produces an ifreqData with the pointer p set for ioctls which require
+// withData produces an ifreqData with the pointer p set for ioctls which require
 // arbitrary pointer data.
-func (ifr ifreq) SetData(p unsafe.Pointer) ifreqData {
+func (ifr Ifreq) withData(p unsafe.Pointer) ifreqData {
 	return ifreqData{
-		name: ifr.Ifrn,
+		name: ifr.raw.Ifrn,
 		data: p,
 	}
 }