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.

Finally, amend LastCap documentation with a link to ListSupported,
as this is what most users are using it for.

Signed-off-by: Kir Kolyshkin <[email protected]>

Author: kolyshkin

capability/capability.go

@@ -137,6 +137,8 @@ func NewFile2(path string) (Capabilities, error) {
 
 // LastCap returns highest valid capability of the running kernel,
 // or an error if it can not be obtained.
+//
+// See also: [ListSupported].
 func LastCap() (Cap, error) {
 	return lastCap()
 }

capability/enum.go

@@ -7,6 +7,8 @@
 
 package capability
 
+import "slices"
+
 type CapType uint
 
 func (c CapType) String() string {
@@ -301,3 +303,30 @@ 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 Linux kernel.
+//
+// Returns nil on platforms other than Linux.
+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/enum_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)