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.Dd November 1, 2022 26.Dt GENETLINK 4 27.Os 28.Sh NAME 29.Nm genetlink 30.Nd Generic Netlink 31.Sh SYNOPSIS 32.In netlink/netlink.h 33.In netlink/netlink_generic.h 34.Ft int 35.Fn socket AF_NETLINK SOCK_DGRAM NETLINK_GENERIC 36.Sh DESCRIPTION 37The 38.Dv NETLINK_GENERIC 39is a "container" family, used for dynamic registration of other families 40belonging to the various subsystems. 41These subsystems provide a string family name during registration and 42receive a dynamically-allocated family id. 43Allocated family identifiers are then used by applications to get access to 44functions provided by that subsystem via netlink. 45There are standard methods for resolving string family names to family 46identifiers. 47A similar mechanism works for the notification groups provided by those 48families. 49.Pp 50All generic netlink families share a common header: 51.Bd -literal 52struct genlmsghdr { 53 uint8_t cmd; /* command within the family */ 54 uint8_t version; /* ABI version for the cmd */ 55 uint16_t reserved; /* reserved: set to 0 */ 56}; 57.Ed 58The family id is encoded in the 59.Dv nlmsg_type 60of the base netlink header. 61The 62.Va cmd 63field is the command identifier within the family. 64The 65.Va version 66field is the command version. 67.Sh METHODS 68The generic Netlink framework provides the base family, 69.Dv GENL_ID_CTRL 70("nlctrl") with a fixed family id. 71This family is used to list the details of all registered families. 72.Pp 73The following messages are supported by the framework: 74.Ss CTRL_CMD_GETFAMILY 75Fetches a single family or all registered families, depending on the 76.Dv NLM_F_DUMP 77flag. 78Each family is reported as 79.Dv CTRL_CMD_NEWFAMILY 80message. 81The following filters are recognised by the kernel: 82.Pp 83.Bd -literal -offset indent -compact 84CTRL_ATTR_FAMILY_ID (uint16_t) current family id assigned by kernel 85CTRL_ATTR_FAMILY_NAME (string) family name 86.Ed 87.Ss TLVs 88.Bl -tag -width indent 89.It Dv CTRL_ATTR_FAMILY_ID 90(uint16_t) Dynamically-assigned family identifier. 91.It Dv CTRL_ATTR_FAMILY_NAME 92(string) Family name. 93.It Dv CTRL_ATTR_HDRSIZE 94(uint32_t) Family mandatory header size (typically 0). 95.It Dv CTRL_ATTR_MAXATTR 96(uint32_t) Maximum attribute number valid for the family. 97.It Dv CTRL_ATTR_OPS 98(nested) List of the operations supported by the family. 99The attribute consists of a list of nested TLVs, with attribute values 100monotonically incremented, starting from 0. 101The following attributes are present in each TLV: 102.Bl -tag -width indent 103.It Dv CTRL_ATTR_OP_ID 104Operation (message) number. 105.It Dv CTRL_ATTR_OP_FLAGS 106Operation flags. 107The following flags are supported: 108.Bd -literal -offset indent -compact 109GENL_ADMIN_PERM requires elevated permissions 110GENL_CMD_CAP_DO operation is a modification request 111GENL_CMD_CAP_DUMP operation is a get/dump request 112.Ed 113.El 114.It Dv CTRL_ATTR_MCAST_GROUPS 115(nested) List of the notification groups supported by the family. 116The attribute consists of a list of nested TLVs, with attribute values 117monotonically incremented, starting from 0. 118The following attributes are present in each TLV: 119.Bl -tag -width indent 120.It Dv CTRL_ATTR_MCAST_GRP_ID 121Group id that can be used in 122.Dv NETLINK_ADD_MEMBERSHIP 123.Xr setsockopt 2 . 124.It Dv CTRL_ATTR_MCAST_GRP_NAME 125(string) Human-readable name of the group. 126.El 127.El 128.Ss Groups 129The following groups are defined: 130.Bd -literal -offset indent -compact 131"notify" Notifies on family registrations/removal. 132.Ed 133.Sh SEE ALSO 134.Xr netlink 4 135.Sh HISTORY 136The 137.Dv NETLINK_GENERIC 138protocol family appeared in 139.Fx 13.2 . 140.Sh AUTHORS 141The netlink was implemented by 142.An -nosplit 143.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . 144It was derived from the Google Summer of Code 2021 project by 145.An Ng Peng Nam Sean . 146