udev

Documentation

Overview

Package udev provides a cgo wrapper around the libudev C library

Index

• type Device
  • func NewDeviceFromDeviceID(id string) *Device
  • func NewDeviceFromSubsystemSysname(subsystem, sysname string) *Device
  • func NewDeviceFromSyspath(syspath string) *Device
  • func (d *Device) Action() string
  • func (d *Device) Devnode() string
  • func (d *Device) Driver() string
  • func (d *Device) Parent() DeviceInfo
  • func (d *Device) Subsystem() string
  • func (d *Device) SysattrValue(sysattr string) string
  • func (d *Device) Sysname() string
  • func (d *Device) Syspath() string
• type DeviceEnumerator
• type DeviceInfo
• type DeviceMonitor
• type Enumerate
  • func NewEnumerate() *Enumerate
  • func (e *Enumerate) AddMatchParent(parent DeviceInfo) error
  • func (e *Enumerate) AddMatchSubsystem(subsystem string) (err error)
  • func (e *Enumerate) AddMatchSysattr(sysattr, value string) (err error)
  • func (e *Enumerate) AddMatchSysname(sysname string) (err error)
  • func (e *Enumerate) AddNomatchSubsystem(subsystem string) (err error)
  • func (e *Enumerate) AddNomatchSysattr(sysattr, value string) (err error)
  • func (e *Enumerate) AddSyspath(syspath string) (err error)
  • func (e *Enumerate) Devices() (it iter.Seq[DeviceInfo], err error)
  • func (e *Enumerate) Subsystems() (it iter.Seq[string], err error)
• type Monitor
  • func NewMonitorFromNetlink(t MonitorType) *Monitor
  • func (m *Monitor) EnableReceiving() (err error)
  • func (m *Monitor) FD() int
  • func (m *Monitor) FilterAddMatchSubsystem(subsystem string) (err error)
  • func (m *Monitor) FilterRemove() (err error)
  • func (m *Monitor) FilterUpdate() (err error)
  • func (m *Monitor) ReceiveDevice() DeviceInfo
  • func (m *Monitor) SetReceiveBufferSize(size int) (err error)
• type MonitorType
  • func (t MonitorType) Name() string

Examples

• Enumerate.Subsystems
• NewDeviceFromDeviceID
• NewDeviceFromSubsystemSysname
• NewDeviceFromSyspath
• NewEnumerate
• NewMonitorFromNetlink

Types

type Device

type Device struct {
	// contains filtered or unexported fields
}

Device wraps a libudev device object

func NewDeviceFromDeviceID

func NewDeviceFromDeviceID(id string) *Device

NewDeviceFromDeviceID returns a pointer to a new device identified by its device id, and nil on error

Example

d := NewDeviceFromDeviceID("c1:8")
fmt.Println(d.Syspath())

Output:
/sys/devices/virtual/mem/random

func NewDeviceFromSubsystemSysname

func NewDeviceFromSubsystemSysname(subsystem, sysname string) *Device

NewDeviceFromSubsystemSysname returns a pointer to a new device identified by its subystem and sysname, and nil on error

Example

d := NewDeviceFromSubsystemSysname("mem", "random")
fmt.Println(d.Syspath())

Output:
/sys/devices/virtual/mem/random

func NewDeviceFromSyspath

func NewDeviceFromSyspath(syspath string) *Device

NewDeviceFromSyspath returns a pointer to a new device identified by its syspath, and nil on error The device is identified by the syspath argument

Example

d := NewDeviceFromSyspath("/sys/devices/virtual/mem/random")
fmt.Println(d.Syspath())

Output:
/sys/devices/virtual/mem/random

func (*Device) Action

func (d *Device) Action() string

Action returns the action for the event. This is only valid if the device was received through a monitor. Devices read from sys do not have an action string. Usual actions are: add, remove, change, online, offline.

func (*Device) Devnode

func (d *Device) Devnode() string

Devnode returns the device node file name belonging to the udev device. The path is an absolute path, and starts with the device directory.

func (*Device) Driver

func (d *Device) Driver() string

Driver returns the driver for the receiver

func (*Device) Parent

func (d *Device) Parent() DeviceInfo

Parent returns the parent Device, or nil if the receiver has no parent Device

func (*Device) Subsystem

func (d *Device) Subsystem() string

Subsystem returns the subsystem string of the udev device. The string does not contain any "/".

func (*Device) SysattrValue

func (d *Device) SysattrValue(sysattr string) string

SysattrValue retrieves the content of a sys attribute file, and returns an empty string if there is no sys attribute value. The retrieved value is cached in the device. Repeated calls will return the same value and not open the attribute again.

func (*Device) Sysname

func (d *Device) Sysname() string

Sysname returns the sysname of the udev device (e.g. ttyS3, sda1...).

func (*Device) Syspath

func (d *Device) Syspath() string

Syspath returns the sys path of the udev device. The path is an absolute path and starts with the sys mount point.

type DeviceEnumerator

type DeviceEnumerator interface {
	// AddMatchSubsystem adds a filter for a subsystem of the device to include in the list.
	AddMatchSubsystem(subsystem string) (err error)

	// AddNomatchSubsystem adds a filter for a subsystem of the device to exclude from the list.
	AddNomatchSubsystem(subsystem string) (err error)

	// AddMatchSysattr adds a filter for a sys attribute at the device to include in the list.
	AddMatchSysattr(sysattr, value string) (err error)

	// AddNomatchSysattr adds a filter for a sys attribute at the device to exclude from the list.
	AddNomatchSysattr(sysattr, value string) (err error)

	// AddMatchSysname adds a filter for the name of the device to include in the list.
	AddMatchSysname(sysname string) (err error)

	// AddMatchParent adds a filter for a parent Device to include in the list.
	AddMatchParent(parent DeviceInfo) error

	// AddSyspath adds a device to the list of enumerated devices, to retrieve it back sorted in dependency order.
	AddSyspath(syspath string) (err error)

	// Devices returns an Iterator over the device syspaths matching the filter, sorted in dependency order.
	// The Iterator is using the github.com/jkeiser/iter package.
	Devices() (it iter.Seq[DeviceInfo], err error)

	// Subsystems returns an Iterator over the subsystem syspaths matching the filter, sorted in dependency order.
	// The Iterator is using the github.com/jkeiser/iter package.
	Subsystems() (it iter.Seq[string], err error)
}

type DeviceInfo

type DeviceInfo interface {
	// Parent returns the parent Device, or nil if the receiver has no parent Device
	Parent() DeviceInfo

	// Subsystem returns the subsystem string of the udev device.
	// The string does not contain any "/".
	Subsystem() string

	// Sysname returns the sysname of the udev device (e.g. ttyS3, sda1...).
	Sysname() string

	// Syspath returns the sys path of the udev device.
	// The path is an absolute path and starts with the sys mount point.
	Syspath() string

	// Devnode returns the device node file name belonging to the udev device.
	// The path is an absolute path, and starts with the device directory.
	Devnode() string

	// Driver returns the driver for the receiver
	Driver() string

	// Action returns the action for the event.
	// This is only valid if the device was received through a monitor.
	// Devices read from sys do not have an action string.
	// Usual actions are: add, remove, change, online, offline.
	Action() string

	// SysattrValue retrieves the content of a sys attribute file, and returns an empty string if there is no sys attribute value.
	// The retrieved value is cached in the device.
	// Repeated calls will return the same value and not open the attribute again.
	SysattrValue(sysattr string) string
}

type DeviceMonitor

type DeviceMonitor interface {
	// FD receives a file descriptor which can be checked for rediness
	FD() int

	EnableReceiving() (err error)

	ReceiveDevice() DeviceInfo

	// SetReceiveBufferSize sets the size of the kernel socket buffer.
	// This call needs the appropriate privileges to succeed.
	SetReceiveBufferSize(size int) (err error)

	// FilterAddMatchSubsystem adds a filter matching the device against a subsystem.
	// This filter is efficiently executed inside the kernel, and libudev subscribers will usually not be woken up for devices which do not match.
	// The filter must be installed before the monitor is switched to listening mode with the DeviceChan function.
	FilterAddMatchSubsystem(subsystem string) (err error)

	// FilterUpdate updates the installed socket filter.
	// This is only needed, if the filter was removed or changed.
	FilterUpdate() (err error)

	// FilterRemove removes all filter from the Monitor.
	FilterRemove() (err error)
}

type Enumerate

type Enumerate struct {
	// contains filtered or unexported fields
}

Enumerate is an opaque struct wrapping a udev enumerate object.

func NewEnumerate

func NewEnumerate() *Enumerate

NewEnumerate returns a pointer to a new enumerate, and nil on error

Example

_ = NewEnumerate()

func (*Enumerate) AddMatchParent

func (e *Enumerate) AddMatchParent(parent DeviceInfo) error

AddMatchParent adds a filter for a parent Device to include in the list.

func (*Enumerate) AddMatchSubsystem

func (e *Enumerate) AddMatchSubsystem(subsystem string) (err error)

AddMatchSubsystem adds a filter for a subsystem of the device to include in the list.

func (*Enumerate) AddMatchSysattr

func (e *Enumerate) AddMatchSysattr(sysattr, value string) (err error)

AddMatchSysattr adds a filter for a sys attribute at the device to include in the list.

func (*Enumerate) AddMatchSysname

func (e *Enumerate) AddMatchSysname(sysname string) (err error)

AddMatchSysname adds a filter for the name of the device to include in the list.

func (*Enumerate) AddNomatchSubsystem

func (e *Enumerate) AddNomatchSubsystem(subsystem string) (err error)

AddNomatchSubsystem adds a filter for a subsystem of the device to exclude from the list.

func (*Enumerate) AddNomatchSysattr

func (e *Enumerate) AddNomatchSysattr(sysattr, value string) (err error)

AddNomatchSysattr adds a filter for a sys attribute at the device to exclude from the list.

func (*Enumerate) AddSyspath

func (e *Enumerate) AddSyspath(syspath string) (err error)

AddSyspath adds a device to the list of enumerated devices, to retrieve it back sorted in dependency order.

func (*Enumerate) Devices

func (e *Enumerate) Devices() (it iter.Seq[DeviceInfo], err error)

Devices returns an Iterator over the device syspaths matching the filter, sorted in dependency order.

func (*Enumerate) Subsystems

func (e *Enumerate) Subsystems() (it iter.Seq[string], err error)

Subsystems returns an Iterator over the subsystem syspaths matching the filter, sorted in dependency order.

Example

e := NewEnumerate()

// Enumerate all subsystem syspaths
dsp, _ := e.Subsystems()
for s := range dsp {
	fmt.Println(s)
}

type Monitor

type Monitor struct {
	// contains filtered or unexported fields
}

Monitor is an opaque object handling an event source

func NewMonitorFromNetlink

func NewMonitorFromNetlink(t MonitorType) *Monitor

NewMonitorFromNetlink returns a pointer to a new monitor listening to a NetLink socket, and nil on error The name argument is either "kernel" or "udev". When passing "kernel" the events are received before they are processed by udev. When passing "udev" the events are received after udev has processed the events and created device nodes. In most cases you will want to use "udev".

Example

_ = NewMonitorFromNetlink(MonitorUdev)

func (*Monitor) EnableReceiving

func (m *Monitor) EnableReceiving() (err error)

func (*Monitor) FD

func (m *Monitor) FD() int

FD receives a file descriptor which can be checked for rediness

func (*Monitor) FilterAddMatchSubsystem

func (m *Monitor) FilterAddMatchSubsystem(subsystem string) (err error)

FilterAddMatchSubsystem adds a filter matching the device against a subsystem. This filter is efficiently executed inside the kernel, and libudev subscribers will usually not be woken up for devices which do not match. The filter must be installed before the monitor is switched to listening mode with the DeviceChan function.

func (*Monitor) FilterRemove

func (m *Monitor) FilterRemove() (err error)

FilterRemove removes all filter from the Monitor.

func (*Monitor) FilterUpdate

func (m *Monitor) FilterUpdate() (err error)

FilterUpdate updates the installed socket filter. This is only needed, if the filter was removed or changed.

func (*Monitor) ReceiveDevice

func (m *Monitor) ReceiveDevice() DeviceInfo

func (*Monitor) SetReceiveBufferSize

func (m *Monitor) SetReceiveBufferSize(size int) (err error)

SetReceiveBufferSize sets the size of the kernel socket buffer. This call needs the appropriate privileges to succeed.

type MonitorType

type MonitorType uint

MonitorType describes how a monitor or enumerator should look for devices.

const (
	// Monitor uses kernel uevents
	MonitorKernel MonitorType = 1
	// Monitor uses udevd
	MonitorUdev MonitorType = 0
)

func (MonitorType) Name

func (t MonitorType) Name() string