capability: deprecate List, add ListKnown, ListSupported

Apparently, most users of capability.List wants the list of supported
capabilities (i.e. they go on to exclude capabilities above the last
known one).

Let's provide ListSupported to such users.

Also, provide ListKnown, and deprecate List.

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>

capability/enum.go

@@ -7,6 +7,8 @@
 
 package capability
 
+import "slices"
+
 type CapType uint
 
 func (c CapType) String() string {
@@ -301,3 +303,28 @@ const (
 	// Introduced in kernel 5.9
 	CAP_CHECKPOINT_RESTORE = Cap(40)
 )
+
+// List returns the list of all capabilities known to the package.
+//
+// Deprecated: use [ListKnown] or [ListSupported] instead.
+func List() []Cap {
+	return ListKnown()
+}
+
+// ListKnown returns the list of all capabilities known to the package.
+func ListKnown() []Cap {
+	return list()
+}
+
+// ListSupported retuns the list of all capabilities known to the package,
+// except those that are not supported by the currently running kernel.
+func ListSupported() []Cap {
+	last, err := LastCap()
+	if err != nil {
+		return nil
+	}
+	return slices.DeleteFunc(list(), func(c Cap) bool {
+		// Remove caps not supported by the kernel.
+		return c > last
+	})
+}

capability/enumgen/gen.go

@@ -43,8 +43,7 @@ func (g *generator) writeStringFunc() {
 
 func (g *generator) writeListFunc() {
 	g.buf.WriteString("\n")
-	g.buf.WriteString("// List returns list of all supported capabilities\n")
-	g.buf.WriteString("func List() []Cap {\n")
+	g.buf.WriteString("func list() []Cap {\n")
 	g.buf.WriteString("return []Cap{\n")
 	for _, cap := range g.caps {
 		fmt.Fprintf(&g.buf, "%s,\n", cap)