Copyright @copyright{} 2025 Dale Mellor

* Introduction::                What is netlink?

* IP Library::                  High-level procedures for network devices.

* ACPI API::                    High-level procedures for receiving ACPI event notifications.

* API Reference::               Low-level procedure reference.

* Concept Index::               Concepts.

* Programming Index::           Data types, procedures, and variables.

 --- The Detailed Node Listing ---

* Link::

* Addr::

* Route::

ACPI API

* ACPI example::

* ACPI reference::

Low-Level API Reference

* Common API::

* Netlink API::

* Rtnetlink API::

Common API

* Data Types::

* Constants::

* Netlink Connections::

Netlink API

* Netlink Headers::

* Standard Message Types::

Rtnetlink API

* Routing Attributes::

* Link Messages::

* Address Messages::

@cindex netlink

@cindex routing protocol

@cindex ACPI protocol

@cindex contributions

@cindex high-level

@cindex intermediate-level

@cindex low-level

Many protocols exist on top of Netlink.  For example, the @emph{routing}

protocol is used to configure network-related functions in the kernel, such as

firewall, route table or IP addresses of interfaces, and the @emph{ACPI}

protocol is used by the Linux kernel to send notifications of changes in

system power usage. (Deep down, these two protocols are very different beasts,

with the former being regarded as a @emph{classical} protocol with very fixed

message formats, and the latter being an example of a @emph{generic} protocol

which entails subscribing to a broadcast channel and deeply introspecting the

transmitted data.)

Lots of other protocols, or families, are provided by Linux, but this library

currently only services the two examples described above.  Of course,

contributions of code which implements others are always welcome!

This library implements code at three levels: at high-level we have the

@ref{IP Library} and @ref{ACPI API} which give immediate access to the

protocols described above; at intermediate level there is the

@ref{Rtnetlink API} which defines special structures and functions used in the

routing protocol, and many of which are borrowed by the ACPI protocol; finally

the low-level details are outlined in the @ref{API Reference}.

@menu

* Link::

* Addr::

* Route::

@end menu

@node ACPI API

@chapter ACPI API

@cindex high-level

@cindex read-selector procedure

@cindex process-data procedure

@cindex close-connection procedure

This chapter describes the high-level procedures contained in the

@code{(netlink acpi)} module that let you monitor the kernel for ACPI event

notifications.  At top level, the requirement is to connect to the kernel's

netlink system, and then you receive three procedures for handling

notifications on the connection.  The first, nominally called

@code{(read-selector)}, provides a file descriptor which you can use in a

@code{select} read-list to wait for a notification to become available on the

connection.

Once you know that data are there waiting to be read, you use the second

provided procedure: @code{(process-data @var{action})}, where the @var{action}

you supply must be a procedure which takes in an @code{event} object, and does

whatever the application needs to do.  Data can be extracted from this object

with @code{event-device-class}, @code{event-bus-id}, @code{event-kind} and

@code{event-data}.

When all is done, the connection should be closed with a call to the third

provided function: @code{(close-connection)}.

@menu

* ACPI example::

* ACPI reference::

@end menu

@node ACPI example

@section acpi-listener example

@cindex acpi-listener application

@cindex ACPI example usage

The following code snippet is the heart of the acpi-listener application

distributed with guile-netlink.  When you run the command at the command line

(it takes no arguments), it will sit there silently and forever, waiting for

an ACPI event to happen (perhaps you can put your computer to suspended sleep

and then re-awaken it), at which time a message will be printed with the data

of that event.

@lisp

;; Use guile-netlink??s ACPI interface.  The use of a prefix is discretionary;

;; it is useful to have in example code.

(use-modules  ((netlink acpi) #:prefix ACPI::))

(define (action event)   ;;  [1]

  ((@@ (ice-9 format) format)

      #t

      "device: ~20a, bus ID: ~15a, type: ~8,'0x, data: ~8,'0x\n"

      (ACPI::event-device-class  event)

      (ACPI::event-bus-id        event)

      (ACPI::event-kind          event)

      (ACPI::event-data          event)))

((@@ (ice-9 receive) receive)

    (ACPI::read-selector  ACPI::process-events  ACPI::close-connection)  ;; [3]

    (ACPI::connect-events)   ;; [2]

    (let loop ()  ;; [4]

      (select (list (ACPI::read-selector)) '() '())

      (ACPI::process-events action)

      (loop))

    (ACPI::close-connection))   ;; [5]

@end lisp

The action we take on receiving events is defined as @code{action} [1], and

simply writes the data elements of the @var{event} to the command-line.

The connection to the kernel is made with the @code{ACPI::connect-events} [2]

procedure call, which gives us the @code{ACPI::read-selector},

@code{ACPI::process-events} and @code{ACPI::close-connection} [3] procedures

for managing the connection.

We then simply go into a tight loop [4] waiting for data, and processing that

when it comes in.

If, by some unattainable miracle, we get out of that loop and want to stop

monitoring for kernel events, we can call the @code{ACPI::close-connection}

procedure [5].

@node ACPI reference

@section ACPI reference

The following procedures are available in the @code{(netlink acpi)} module.

@deffn {Scheme Procedure} connect-events

Open a connection to the kernel, and set it up to listen for ACPI event

notifications.  The procedure returns three new procedures for managing this

connection: @dfn{read-selector} which returns a file descriptor which can be

passed to the @code{select} procedure to wait for data from the kernel,

@dfn{process-data @var{action}} which reads and evaluates the data, and calls

@code{ACTION @var{event}} on it, and finally @dfn{close-connection} which will

terminate the connection with the kernel.

@end deffn

@deffn {Scheme Procedure} event-display-class @var{event}

Extract the display class from the @var{event}.  This will be a string.

@end deffn

@deffn {Scheme Procedure} event-bus-id @var{event}

Extract the bus-id from the @var{event}, again a string.

@end deffn

@deffn {Scheme Procedure} event-kind @var{event}

Extract the type of the @var{event}, a number, nominally unsigned 32 bit.

@end deffn

@deffn {Scheme Procedure} event-data @var{event}

Extract the data from the @var{event}, a number, also nominally unsigned 32

bit.

@end deffn

@chapter Low-Level API Reference

@menu

* Common API::

* Netlink API::

* Rtnetlink API::

@end menu

@menu

* Data Types::

* Constants::

* Netlink Connections::

@end menu

@menu

* Netlink Headers::

* Standard Message Types::

@end menu

@menu

* Routing Attributes::

* Link Messages::

* Address Messages::

@end menu