The Linux Kernel
5.15.0
  • The Linux kernel user’s and administrator’s guide
  • Kernel Build System
  • The Linux kernel firmware guide
  • Open Firmware and Devicetree
  • The Linux kernel user-space API guide
  • Working with the kernel development community
  • Development tools for the kernel
  • How to write kernel documentation
  • Kernel Hacking Guides
  • Linux Tracing Technologies
  • Kernel Maintainer Handbook
  • fault-injection
  • Kernel Livepatching
  • The Linux driver implementer’s API guide
  • Core API Documentation
    • Core utilities
    • Data structures and low-level utilities
    • Concurrency primitives
    • Low-level hardware management
    • Memory management
    • Interfaces for kernel debugging
    • Everything else
      • Reed-Solomon Library Programming Interface
      • Netlink notes for kernel developers
        • General guidance
        • Netlink specification
  • locking
  • Accounting
  • Block
  • cdrom
  • Linux CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel
  • Integrated Drive Electronics (IDE)
  • Frame Buffer
  • fpga
  • Human Interface Devices (HID)
  • I2C/SMBus Subsystem
  • Industrial I/O
  • ISDN
  • InfiniBand
  • LEDs
  • NetLabel
  • Linux Networking Documentation
  • pcmcia
  • Power Management
  • TCM Virtual Device
  • timers
  • Serial Peripheral Interface (SPI)
  • 1-Wire Subsystem
  • Linux Watchdog Support
  • Linux Virtualization Support
  • The Linux Input Documentation
  • Linux Hardware Monitoring
  • Linux GPU Driver Developer’s Guide
  • Security Documentation
  • Linux Sound Subsystem Documentation
  • Linux Kernel Crypto API
  • Filesystems in the Linux kernel
  • Linux Memory Management Documentation
  • BPF Documentation
  • USB support
  • Linux PCI Bus Subsystem
  • Linux SCSI Subsystem
  • Assorted Miscellaneous Devices Documentation
  • Linux Scheduler
  • MHI
  • Assembler Annotations
  • CPU Architectures
  • Unsorted Documentation
  • Atomic Types
  • Atomic bitops
  • Memory Barriers
  • General notification mechanism
  • Translations
The Linux Kernel
  • Docs »
  • Core API Documentation »
  • Netlink notes for kernel developers
  • View page source

Netlink notes for kernel developers¶

General guidance¶

Attribute enums¶

Older families often define “null” attributes and commands with value of 0 and named unspec. This is supported (type: unused) but should be avoided in new families. The unspec enum values are not used in practice, so just set the value of the first attribute to 1.

Message enums¶

Use the same command IDs for requests and replies. This makes it easier to match them up, and we have plenty of ID space.

Use separate command IDs for notifications. This makes it easier to sort the notifications from replies (and present them to the user application via a different API than replies).

Answer requests¶

Older families do not reply to all of the commands, especially NEW / ADD commands. User only gets information whether the operation succeeded or not via the ACK. Try to find useful data to return. Once the command is added whether it replies with a full message or only an ACK is uAPI and cannot be changed. It’s better to err on the side of replying.

Specifically NEW and ADD commands should reply with information identifying the created object such as the allocated object’s ID (without having to resort to using NLM_F_ECHO).

NLM_F_ECHO¶

Make sure to pass the request info to genl_notify() to allow NLM_F_ECHO to take effect. This is useful for programs that need precise feedback from the kernel (for example for logging purposes).

Support dump consistency¶

If iterating over objects during dump may skip over objects or repeat them - make sure to report dump inconsistency with NLM_F_DUMP_INTR. This is usually implemented by maintaining a generation id for the structure and recording it in the seq member of struct netlink_callback.

Netlink specification¶

Documentation of the Netlink specification parts which are only relevant to the kernel space.

Globals¶

kernel-policy¶

Defines if the kernel validation policy is per operation (per-op) or for the entire family (global). New families should use per-op (default) to be able to narrow down the attributes accepted by a specific command.

checks¶

Documentation for the checks sub-sections of attribute specs.

unterminated-ok¶

Accept strings without the null-termination (for legacy families only). Switches from the NLA_NUL_STRING to NLA_STRING policy type.

max-len¶

Defines max length for a binary or string attribute (corresponding to the len member of struct nla_policy). For string attributes terminating null character is not counted towards max-len.

The field may either be a literal integer value or a name of a defined constant. String types may reduce the constant by one (i.e. specify max-len: CONST - 1) to reserve space for the terminating character so implementations should recognize such pattern.

min-len¶

Similar to max-len but defines minimum length.

Next Previous

© Copyright The kernel development community.

Built with Sphinx using a theme provided by Read the Docs.