share/man/man4/genetlink.4

   1 .\"
   2 .\" Copyright (C) 2022 Alexander Chernikov <melifaro@FreeBSD.org>.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd November 1, 2022
  28 .Dt GENETLINK 4
  29 .Os
  30 .Sh NAME
  31 .Nm genetlink
  32 .Nd Generic Netlink
  33 .Sh SYNOPSIS
  34 .In netlink/netlink.h
  35 .In netlink/netlink_generic.h
  36 .Ft int
  37 .Fn socket AF_NETLINK SOCK_DGRAM NETLINK_GENERIC
  38 .Sh DESCRIPTION
  39 The
  40 .Dv NETLINK_GENERIC
  41 is a "container" family, used for dynamic registration of other families
  42 belonging to the various subsystems.
  43 These subsystems provide a string family name during registration and
  44 receive a dynamically-allocated family id.
  45 Allocated family identifiers are then used by applications to get access to
  46 functions provided by that subsystem via netlink.
  47 There are standard methods for resolving string family names to family
  48 identifiers.
  49 A similar mechanism works for the notification groups provided by those
  50 families.
  51 .Pp
  52 All generic netlink families share a common header:
  53 .Bd -literal
  54 struct genlmsghdr {
  55         uint8_t         cmd;            /* command within the family */
  56         uint8_t         version;        /* ABI version for the cmd */
  57         uint16_t        reserved;       /* reserved: set to 0 */
  58 };
  59 .Ed
  60 The family id is encoded in the
  61 .Dv nlmsg_type
  62 of the base netlink header.
  63 The
  64 .Va cmd
  65 field is the command identifier within the family.
  66 The
  67 .Va version
  68 field is the command version.
  69 .Sh METHODS
  70 The generic Netlink framework provides the base family,
  71 .Dv GENL_ID_CTRL
  72 ("nlctrl") with a fixed family id.
  73 This family is used to list the details of all registered families.
  74 .Pp
  75 The following messages are supported by the framework:
  76 .Ss CTRL_CMD_GETFAMILY
  77 Fetches a single family or all registered families, depending on the
  78 .Dv NLM_F_DUMP
  79 flag.
  80 Each family is reported as
  81 .Dv CTRL_CMD_NEWFAMILY
  82 message.
  83 The following filters are recognised by the kernel:
  84 .Pp
  85 .Bd -literal -offset indent -compact
  86 CTRL_ATTR_FAMILY_ID     (uint16_t) current family id assigned by kernel
  87 CTRL_ATTR_FAMILY_NAME   (string) family name
  88 .Ed
  89 .Ss TLVs
  90 .Bl -tag -width indent
  91 .It Dv CTRL_ATTR_FAMILY_ID
  92 (uint16_t) Dynamically-assigned family identifier.
  93 .It Dv CTRL_ATTR_FAMILY_NAME
  94 (string) Family name.
  95 .It Dv CTRL_ATTR_HDRSIZE
  96 (uint32_t) Family mandatory header size (typically 0).
  97 .It Dv CTRL_ATTR_MAXATTR
  98 (uint32_t) Maximum attribute number valid for the family.
  99 .It Dv CTRL_ATTR_OPS
 100 (nested) List of the operations supported by the family.
 101 The attribute consists of a list of nested TLVs, with attribute values
 102 monotonically incremented, starting from 0.
 103 The following attributes are present in each TLV:
 104 .Bl -tag -width indent
 105 .It Dv CTRL_ATTR_OP_ID
 106 Operation (message) number.
 107 .It Dv CTRL_ATTR_OP_FLAGS
 108 Operation flags.
 109 The following flags are supported:
 110 .Bd -literal -offset indent -compact
 111 GENL_ADMIN_PERM         requires elevated permissions
 112 GENL_CMD_CAP_DO         operation is a modification request
 113 GENL_CMD_CAP_DUMP       operation is a get/dump request
 114 .Ed
 115 .El
 116 .It Dv CTRL_ATTR_MCAST_GROUPS
 117 (nested) List of the notification groups supported by the family.
 118 The attribute consists of a list of nested TLVs, with attribute values
 119 monotonically incremented, starting from 0.
 120 The following attributes are present in each TLV:
 121 .Bl -tag -width indent
 122 .It Dv CTRL_ATTR_MCAST_GRP_ID
 123 Group id that can be used in
 124 .Dv NETLINK_ADD_MEMBERSHIP
 125 .Xr setsockopt 2 .
 126 .It Dv CTRL_ATTR_MCAST_GRP_NAME
 127 (string) Human-readable name of the group.
 128 .El
 129 .El
 130 .Ss Groups
 131 The following groups are defined:
 132 .Bd -literal -offset indent -compact
 133 "notify"        Notifies on family registrations/removal.
 134 .Ed
 135 .Sh SEE ALSO
 136 .Xr netlink 4
 137 .Sh HISTORY
 138 The
 139 .Dv NETLINK_GENERIC
 140 protocol family appeared in
 141 .Fx 13.2 .
 142 .Sh AUTHORS
 143 The netlink was implementated by
 144 .An -nosplit
 145 .An Alexander Chernikov Aq Mt melifaro@FreeBSD.org .
 146 It was derived from the Google Summer of Code 2021 project by
 147 .An Ng Peng Nam Sean .