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 39The 40.Dv NETLINK_GENERIC 41is a "container" family, used for dynamic registration of other families 42belonging to the various subsystems. 43These subsystems provide a string family name during registration and 44receive a dynamically-allocated family id. 45Allocated family identifiers are then used by applications to get access to 46functions provided by that subsystem via netlink. 47There are standard methods for resolving string family names to family 48identifiers. 49A similar mechanism works for the notification groups provided by those 50families. 51.Pp 52All generic netlink families share a common header: 53.Bd -literal 54struct 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 60The family id is encoded in the 61.Dv nlmsg_type 62of the base netlink header. 63The 64.Va cmd 65field is the command identifier within the family. 66The 67.Va version 68field is the command version. 69.Sh METHODS 70The generic Netlink framework provides the base family, 71.Dv GENL_ID_CTRL 72("nlctrl") with a fixed family id. 73This family is used to list the details of all registered families. 74.Pp 75The following messages are supported by the framework: 76.Ss CTRL_CMD_GETFAMILY 77Fetches a single family or all registered families, depending on the 78.Dv NLM_F_DUMP 79flag. 80Each family is reported as 81.Dv CTRL_CMD_NEWFAMILY 82message. 83The following filters are recognised by the kernel: 84.Pp 85.Bd -literal -offset indent -compact 86CTRL_ATTR_FAMILY_ID (uint16_t) current family id assigned by kernel 87CTRL_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. 101The attribute consists of a list of nested TLVs, with attribute values 102monotonically incremented, starting from 0. 103The following attributes are present in each TLV: 104.Bl -tag -width indent 105.It Dv CTRL_ATTR_OP_ID 106Operation (message) number. 107.It Dv CTRL_ATTR_OP_FLAGS 108Operation flags. 109The following flags are supported: 110.Bd -literal -offset indent -compact 111GENL_ADMIN_PERM requires elevated permissions 112GENL_CMD_CAP_DO operation is a modification request 113GENL_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. 118The attribute consists of a list of nested TLVs, with attribute values 119monotonically incremented, starting from 0. 120The following attributes are present in each TLV: 121.Bl -tag -width indent 122.It Dv CTRL_ATTR_MCAST_GRP_ID 123Group 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 131The 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 138The 139.Dv NETLINK_GENERIC 140protocol family appeared in 141.Fx 14.0 . 142.Sh AUTHORS 143The netlink was implementated by 144.An -nosplit 145.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . 146It was derived from the Google Summer of Code 2021 project by 147.An Ng Peng Nam Sean . 148