udev

package module
v0.0.0-...-8195ba1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2021 License: Apache-2.0 Imports: 9 Imported by: 0

README

go-udev

Go bindings for libudev

Documentation

Documentation is on Godoc. GoDoc

Documentation

Overview

Package udev provides a cgo wrapper around the libudev C library

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Device 

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

Device wraps a libudev device object

Example 
// Create Udev
u := Udev{}

// Create new Device based on subsystem and sysname
d := u.NewDeviceFromSubsystemSysname("mem", "zero")

// Extract information
fmt.Printf("Sysname:%v\n", d.Sysname())
fmt.Printf("Syspath:%v\n", d.Syspath())
fmt.Printf("Devpath:%v\n", d.Devpath())
fmt.Printf("Devnode:%v\n", d.Devnode())
fmt.Printf("Subsystem:%v\n", d.Subsystem())
fmt.Printf("Devtype:%v\n", d.Devtype())
fmt.Printf("Sysnum:%v\n", d.Sysnum())
fmt.Printf("IsInitialized:%v\n", d.IsInitialized())
fmt.Printf("Driver:%v\n", d.Driver())

// Use one of the iterators
it := d.PropertyIterator()
it.Each(func(item interface{}) {
	kv := item.([]string)
	_ = fmt.Sprintf("Property:%v=%v\n", kv[0], kv[1])
})

Output:

Sysname:zero
Syspath:/sys/devices/virtual/mem/zero
Devpath:/devices/virtual/mem/zero
Devnode:/dev/zero
Subsystem:mem
Devtype:
Sysnum:
IsInitialized:true
Driver:

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) DevlinkIterator 

func (d *Device) DevlinkIterator() iter.Iterator

DevlinkIterator returns an Iterator over the device links pointing to the device file of the udev device. The Iterator is using the github.com/jkeiser/iter package. Values are returned as an interface{} and should be cast to string. 

func (d *Device) Devlinks() (r map[string]struct{})

Devlinks retrieves the map of device links pointing to the device file of the udev device. The path is an absolute path, and starts with the device directory.

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) Devnum 

func (d *Device) Devnum() Devnum

Devnum returns the device major/minor number.

func (*Device) Devpath 

func (d *Device) Devpath() string

Devpath returns the kernel devpath value of the udev device. The path does not contain the sys mount point, and starts with a '/'.

func (*Device) Devtype 

func (d *Device) Devtype() string

Devtype returns the devtype string of the udev device.

func (*Device) Driver 

func (d *Device) Driver() string

Driver returns the driver for the receiver

func (*Device) HasTag 

func (d *Device) HasTag(tag string) bool

HasTag checks if the udev device has the tag specified

func (*Device) IsInitialized 

func (d *Device) IsInitialized() bool

IsInitialized checks if udev has already handled the device and has set up device node permissions and context, or has renamed a network device.

This is only implemented for devices with a device node or network interfaces. All other devices return 1 here.

func (*Device) Parent 

func (d *Device) Parent() *Device

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

func (*Device) ParentWithSubsystemDevtype 

func (d *Device) ParentWithSubsystemDevtype(subsystem, devtype string) *Device

ParentWithSubsystemDevtype returns the parent Device with the given subsystem and devtype, or nil if the receiver has no such parent device

func (*Device) Properties 

func (d *Device) Properties() (r map[string]string)

Properties retrieves a map[string]string of key/value device properties of the udev device.

func (*Device) PropertyIterator 

func (d *Device) PropertyIterator() iter.Iterator

PropertyIterator returns an Iterator over the key/value device properties of the udev device. The Iterator is using the github.com/jkeiser/iter package. Values are returned as an interface{} and should be cast to []string, which will have length 2 and represent a Key/Value pair.

func (*Device) PropertyValue 

func (d *Device) PropertyValue(key string) string

PropertyValue retrieves the value of a device property

func (*Device) Seqnum 

func (d *Device) Seqnum() uint64

Seqnum returns the sequence number of the event. This is only valid if the device was received through a monitor. Devices read from sys do not have a sequence number.

func (*Device) SetSysattrValue 

func (d *Device) SetSysattrValue(sysattr, value string) (err error)

SetSysattrValue sets the content of a sys attribute file, and returns an error if this fails.

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) SysattrIterator 

func (d *Device) SysattrIterator() iter.Iterator

SysattrIterator returns an Iterator over the systems attributes of the udev device. The Iterator is using the github.com/jkeiser/iter package. Values are returned as an interface{} and should be cast to string.

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) Sysattrs 

func (d *Device) Sysattrs() (r map[string]struct{})

Sysattrs returns a Set with the systems attributes of the udev device.

func (*Device) Sysname 

func (d *Device) Sysname() string

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

func (*Device) Sysnum 

func (d *Device) Sysnum() string

Sysnum returns the trailing number of of the device name

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.

func (*Device) TagIterator 

func (d *Device) TagIterator() iter.Iterator

TagIterator returns an Iterator over the tags attached to the udev device. The Iterator is using the github.com/jkeiser/iter package. Values are returned as an interface{} and should be cast to string.

func (*Device) Tags 

func (d *Device) Tags() (r map[string]struct{})

Tags retrieves the Set of tags attached to the udev device.

func (*Device) UsecSinceInitialized 

func (d *Device) UsecSinceInitialized() uint64

UsecSinceInitialized returns the number of microseconds passed since udev set up the device for the first time. This is only implemented for devices with need to store properties in the udev database. All other devices return 0 here.

type Devnum 

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

Devnum is a kernel device number

func MkDev 

func MkDev(major, minor int) Devnum

MkDev creates a Devnum from a major and minor number

func (Devnum) Major 

func (d Devnum) Major() int

Major returns the major part of a Devnum

func (Devnum) Minor 

func (d Devnum) Minor() int

Minor returns the minor part of a Devnum

type Enumerate 

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

Enumerate is an opaque struct wrapping a udev enumerate object.

func (*Enumerate) AddMatchIsInitialized 

func (e *Enumerate) AddMatchIsInitialized() (err error)

AddMatchIsInitialized adds a filter matching only devices which udev has set up already. This makes sure, that the device node permissions and context are properly set and that network devices are fully renamed. Usually, devices which are found in the kernel but not already handled by udev, have still pending events. Services should subscribe to monitor events and wait for these devices to become ready, instead of using uninitialized devices. For now, this will not affect devices which do not have a device node and are not network interfaces.

func (*Enumerate) AddMatchParent 

func (e *Enumerate) AddMatchParent(parent *Device) (err error)

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

func (*Enumerate) AddMatchProperty 

func (e *Enumerate) AddMatchProperty(property, value string) (err error)

AddMatchProperty adds a filter for a property of the 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) AddMatchTag 

func (e *Enumerate) AddMatchTag(tag string) (err error)

AddMatchTag adds a filter for a tag 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) DeviceIterator 

func (e *Enumerate) DeviceIterator() (it iter.Iterator, err error)

DeviceIterator returns an Iterator over the Devices matching the filter, sorted in dependency order. The Iterator is using the github.com/jkeiser/iter package. Values are returned as an interface{} and should be cast to *Device.

func (*Enumerate) DeviceSubsystemIterator 

func (e *Enumerate) DeviceSubsystemIterator() (it iter.Iterator, err error)

DeviceSubsystemIterator returns an Iterator over the subsystem syspaths matching the filter, sorted in dependency order. The Iterator is using the github.com/jkeiser/iter package. Values are returned as an interface{} and should be cast to string.

func (*Enumerate) DeviceSyspathIterator 

func (e *Enumerate) DeviceSyspathIterator() (it iter.Iterator, err error)

DeviceSyspathIterator returns an Iterator over the device syspaths matching the filter, sorted in dependency order. The Iterator is using the github.com/jkeiser/iter package. Values are returned as an interface{} and should be cast to string.

func (*Enumerate) DeviceSyspaths 

func (e *Enumerate) DeviceSyspaths() (s []string, err error)

DeviceSyspaths retrieves a list of device syspaths matching the filter, sorted in dependency order.

Example 
// Create Udev and Enumerate
u := Udev{}
e := u.NewEnumerate()

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

Output:

func (*Enumerate) Devices 

func (e *Enumerate) Devices() (m []*Device, err error)

Devices retrieves a list of Devices matching the filter, sorted in dependency order.

Example 
// Create Udev and Enumerate
u := Udev{}
e := u.NewEnumerate()

// Add some FilterAddMatchSubsystemDevtype
e.AddMatchSubsystem("block")
e.AddMatchIsInitialized()
devices, _ := e.Devices()
for i := range devices {
	device := devices[i]
	fmt.Println(device.Syspath())
}

Output:

func (*Enumerate) SubsystemSyspaths 

func (e *Enumerate) SubsystemSyspaths() (s []string, err error)

SubsystemSyspaths retrieves a list of subsystem syspaths matching the filter, sorted in dependency order.

Example 
// Create Udev and Enumerate
u := Udev{}
e := u.NewEnumerate()

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

Output:

type Monitor 

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

Monitor is an opaque object handling an event source

Example 
// Create Udev and Monitor
u := Udev{}
m := u.NewMonitorFromNetlink("udev")

// Add filters to monitor
m.FilterAddMatchSubsystemDevtype("block", "disk")
m.FilterAddMatchTag("systemd")

// Create a context
ctx, cancel := context.WithCancel(context.Background())

// Start monitor goroutine and get receive channel
ch, _ := m.DeviceChan(ctx)

// WaitGroup for timers
var wg sync.WaitGroup
wg.Add(3)
go func() {
	fmt.Println("Started listening on channel")
	for d := range ch {
		fmt.Println("Event:", d.Syspath(), d.Action())
	}
	fmt.Println("Channel closed")
	wg.Done()
}()
go func() {
	fmt.Println("Starting timer to update filter")
	<-time.After(2 * time.Second)
	fmt.Println("Removing filter")
	m.FilterRemove()
	fmt.Println("Updating filter")
	m.FilterUpdate()
	wg.Done()
}()
go func() {
	fmt.Println("Starting timer to signal done")
	<-time.After(4 * time.Second)
	fmt.Println("Signalling done")
	cancel()
	wg.Done()
}()
wg.Wait()

Output:

func (*Monitor) DeviceChan 

func (m *Monitor) DeviceChan(ctx context.Context) (<-chan *Device, error)

DeviceChan binds the udev_monitor socket to the event source and spawns a goroutine. The goroutine efficiently waits on the monitor socket using epoll. Data is received from the udev monitor socket and a new Device is created with the data received. Pointers to the device are sent on the returned channel. The function takes a context as argument, which when done will stop the goroutine and close the device channel. Only socket connections with uid=0 are accepted.

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) FilterAddMatchSubsystemDevtype 

func (m *Monitor) FilterAddMatchSubsystemDevtype(subsystem, devtype string) (err error)

FilterAddMatchSubsystemDevtype adds a filter matching the device against a subsystem and device type. 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) FilterAddMatchTag 

func (m *Monitor) FilterAddMatchTag(tag string) (err error)

FilterAddMatchTag adds a filter matching the device against a tag. 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.

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) 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 Udev 

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

Udev is an opaque struct wraping a udev library context

func (*Udev) NewDeviceFromDeviceID 

func (u *Udev) NewDeviceFromDeviceID(id string) *Device

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

Example 
u := Udev{}
d := u.NewDeviceFromDeviceID("c1:8")
fmt.Println(d.Syspath())

Output:

/sys/devices/virtual/mem/random

func (*Udev) NewDeviceFromDevnum 

func (u *Udev) NewDeviceFromDevnum(deviceType uint8, n Devnum) *Device

NewDeviceFromDevnum returns a pointer to a new device identified by its Devnum, and nil on error deviceType is 'c' for a character device and 'b' for a block device

Example 
u := Udev{}
d := u.NewDeviceFromDevnum('c', MkDev(1, 8))
fmt.Println(d.Syspath())

Output:

/sys/devices/virtual/mem/random

func (*Udev) NewDeviceFromSubsystemSysname 

func (u *Udev) NewDeviceFromSubsystemSysname(subsystem, sysname string) *Device

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

Example 
u := Udev{}
d := u.NewDeviceFromSubsystemSysname("mem", "random")
fmt.Println(d.Syspath())

Output:

/sys/devices/virtual/mem/random

func (*Udev) NewDeviceFromSyspath 

func (u *Udev) 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 
u := Udev{}
d := u.NewDeviceFromSyspath("/sys/devices/virtual/mem/random")
fmt.Println(d.Syspath())

Output:

/sys/devices/virtual/mem/random

func (*Udev) NewEnumerate 

func (u *Udev) NewEnumerate() *Enumerate

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

Example 
u := Udev{}
_ = u.NewEnumerate()

Output:


func (u *Udev) NewMonitorFromNetlink(name string) *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".

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.