ioctl

README

ioctl

A tiny package to help with dealing with constructing Linux ioctl(2) request values that are not already included in the sys/unix standard package.

For devcontainer instructions, please see the section "DevContainer" below.

Usage

A good example are ioctl_ns(2) operations on Linux namespaces. For instance, this ioctl operation request value is defined in include/uapi/linux/nsfs.h in the Linux kernel C headers as follows:

#define NSIO	0xb7

/* Returns a file descriptor that refers to an owning user namespace */
#define NS_GET_USERNS		_IO(NSIO, 0x1)

These definitions can now be applied to Go code as follows:

import "github.com/thediveo/ioctl"

const NSIO = 0xb7
var NS_GET_USERNS = ioctl.IO(NSIO, 0x1)

func main() {
  fd, err := ioctl.RetFd(nsfd, NS_GET_USERNS)
}

DevContainer

[!CAUTION]

Do not use VSCode's "Dev Containers: Clone Repository in Container Volume" command, as it is utterly broken by design, ignoring .devcontainer/devcontainer.json.

1. git clone https://github.com/thediveo/enumflag
2. in VSCode: Ctrl+Shift+P, "Dev Containers: Open Workspace in Container..."
3. select enumflag.code-workspace and off you go...

Supported Go Versions

native supports versions of Go that are noted by the Go release policy, that is, major versions N and N-1 (where N is the current major version).

Copyright and License

Copyright 2023, 2025 Harald Albrecht, licensed under the Apache License, Version 2.0.

Documentation

Overview

Package ioctl is a thin convenience wrapper for working with those ioctl request numbers that are not defined as plain numbers but instead as macros in the Linux kernel header files.

Example

The request values for ioctl_ns(2) operations are defined using C macros in include/uapi/linux/nsfs.h in the Linux kernel header sources as follows:

#define NSIO 0xb7

// Returns a file descriptor that refers to an owning user namespace
#define NS_GET_USERNS _IO(NSIO, 0x1)

These definitions can now be applied to Go code as follows:

import "github.com/thediveo/ioctl"

const NSIO = 0xb7
var NS_GET_USERNS = ioctl.IO(NSIO, 0x1)

fd, err := ioctl.RetFd(nsfd, NS_GET_USERNS)

Index

• Constants
• func IO(ioctype, nr uint) uint
• func IOC(dir, ioctype, nr, size uint) uint
• func IOR(ioctype, nr, size uint) uint
• func IORW(ioctype, nr, size uint) uint
• func IOW(ioctype, nr, size uint) uint
• func RetFd(fd int, request uint) (int, error)

Constants

const (
	IOC_NRBITS   = 8
	IOC_TYPEBITS = 8
	IOC_SIZEBITS = 14

	IOC_NRSHIFT   = 0
	IOC_TYPESHIFT = IOC_NRSHIFT + IOC_NRBITS
	IOC_SIZESHIFT = IOC_TYPESHIFT + IOC_TYPEBITS
	IOC_DIRSHIFT  = IOC_SIZESHIFT + IOC_SIZEBITS

	IOC_NONE  = uint(0)
	IOC_WRITE = uint(1)
	IOC_READ  = uint(2)
)

This is ugly ioctl command (request) enconding stuff. Requests are 32 bits in total, with the command in the lower 16 bits and the size of the parameter structure taking up the lower 14 bits of the request's upper 16 bits.

ATTENTION: the following definitions follow the kernel's ioctl.h. They hold “only” for the “asm-generic” platforms, such as x86, arm, and others. Currently the only platforms having a different ioctl request field mapping are: alpha, mips, powerpc, and sparc. And alpha isn't even an architecture supported by Go, go figure.

We keep the original C identifiers on purpose (but have to remove the leading “_”) and otherwise don't care about patronizing linters.

Functions

func IO

func IO(ioctype, nr uint) uint

IO returns an ioctl(2) request value for a request that doesn't have any additional request parameter.

func IOC

func IOC(dir, ioctype, nr, size uint) uint

IOC returns an ioctl(2) request value, calculated from the specific ioctl call properties: parameter in/out direction, type of ioctl, command number, and finally parameter size.

func IOR

func IOR(ioctype, nr, size uint) uint

IOR returns an ioctl(2) request value for a request that has an additional request parameter that the userland wants to read and the kernel is writing.

func IORW

func IORW(ioctype, nr, size uint) uint

IORW returns an ioctl(2) request value for a request that has an additional request parameter that the userland first wants to write, the kernel then reads and updates it, and the userland finally wants to read it afterwards.

func IOW

func IOW(ioctype, nr, size uint) uint

IOW returns an ioctl(2) request value for a request that has an additional request parameter that the userland wants to read and the kernel is writing.

func RetFd

func RetFd(fd int, request uint) (int, error)

RetFd issues the specified ioctĺ request and returns the successful result as a file descriptor, or an error. In contrast to unix.IoctlRetInt, RetFd returns an invalid file descriptor -1