From: Alejandro Colomar <alx@kernel.org>
Date: Sat, 17 Aug 2024 20:09:26 +0000 (+0200)
Subject: keyctl.2, KEYCTL_INVALIDATE.2const: Split KEYCTL_INVALIDATE from keyctl(2)
X-Git-Tag: man-pages-6.10~181^2~8
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fca99eac523eb96bfa69797d57952d2ea69f4601;p=thirdparty%2Fman-pages.git

keyctl.2, KEYCTL_INVALIDATE.2const: Split KEYCTL_INVALIDATE from keyctl(2)

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

diff --git a/man/man2/keyctl.2 b/man/man2/keyctl.2
index d5afe7929..09a952f46 100644
--- a/man/man2/keyctl.2
+++ b/man/man2/keyctl.2
@@ -83,47 +83,8 @@ are:
 .BR KEYCTL_GET_SECURITY (2const)
 .TQ
 .BR KEYCTL_SESSION_TO_PARENT (2const)
-.TP
-.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
-.\" commit fd75815f727f157a05f4c96b5294a4617c0557da
-Mark a key as invalid.
-.IP
-The ID of the key to be invalidated is specified in
-.I arg2
-(cast to
-.IR key_serial_t ).
-.IP
-To invalidate a key,
-the caller must have
-.I search
-permission on the key.
-.\" CAP_SYS_ADMIN is permitted to invalidate certain special keys
-.IP
-This operation marks the key as invalid
-and schedules immediate garbage collection.
-The garbage collector removes the invalidated key from all keyrings and
-deletes the key when its reference count reaches zero.
-After this operation,
-the key will be ignored by all searches,
-even if it is not yet deleted.
-.IP
-Keys that are marked invalid become invisible to normal key operations
-immediately, though they are still visible in
-.I /proc/keys
-(marked with an 'i' flag)
-until they are actually removed.
-.IP
-The arguments
-.IR arg3 ,
-.IR arg4 ,
-and
-.I arg5
-are ignored.
-.IP
-This operation is exposed by
-.I libkeyutils
-via the function
-.BR keyctl_invalidate (3).
+.TQ
+.BR KEYCTL_INVALIDATE (2const)
 .TP
 .BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
 .\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
@@ -915,7 +876,6 @@ main(int argc, char *argv[])
 .BR keyctl_dh_compute (3),
 .BR keyctl_dh_compute_alloc (3),
 .BR keyctl_get_persistent (3),
-.BR keyctl_invalidate (3),
 .BR recursive_key_scan (3),
 .BR recursive_session_key_scan (3),
 .BR capabilities (7),
diff --git a/man/man2const/KEYCTL_INVALIDATE.2const b/man/man2const/KEYCTL_INVALIDATE.2const
new file mode 100644
index 000000000..0f2078d64
--- /dev/null
+++ b/man/man2const/KEYCTL_INVALIDATE.2const
@@ -0,0 +1,87 @@
+.\" Copyright 2016, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Copyright 2016, Eugene Syromyatnikov <evgsyr@gmail.com>
+.\" A very few fragments remain from an earlier version of this page
+.\" written by David Howells (dhowells@redhat.com)
+.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH KEYCTL_INVALIDATE 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+KEYCTL_INVALIDATE
+\-
+invalidate a key
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/keyctl.h>" "  /* Definition of " KEY* " constants */"
+.BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "long syscall(SYS_keyctl, KEYCTL_INVALIDATE, unsigned long " arg2 ,
+.BI "             unsigned long " arg3 ", unsigned long " arg4 ,
+.BI "             unsigned long " arg5 );
+.fi
+.SH DESCRIPTION
+.TP
+.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
+.\" commit fd75815f727f157a05f4c96b5294a4617c0557da
+Mark a key as invalid.
+.IP
+The ID of the key to be invalidated is specified in
+.I arg2
+(cast to
+.IR key_serial_t ).
+.IP
+To invalidate a key,
+the caller must have
+.I search
+permission on the key.
+.\" CAP_SYS_ADMIN is permitted to invalidate certain special keys
+.IP
+This operation marks the key as invalid
+and schedules immediate garbage collection.
+The garbage collector removes the invalidated key from all keyrings and
+deletes the key when its reference count reaches zero.
+After this operation,
+the key will be ignored by all searches,
+even if it is not yet deleted.
+.IP
+Keys that are marked invalid become invisible to normal key operations
+immediately, though they are still visible in
+.I /proc/keys
+(marked with an 'i' flag)
+until they are actually removed.
+.IP
+The arguments
+.IR arg3 ,
+.IR arg4 ,
+and
+.I arg5
+are ignored.
+.IP
+This operation is exposed by
+.I libkeyutils
+via the function
+.BR keyctl_invalidate (3).
+.SH RETURN VALUE
+On success,
+0 is returned.
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH VERSIONS
+A wrapper is provided in the
+.I libkeyutils
+library:
+.BR keyctl_invalidate (3).
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 3.5.
+.SH SEE ALSO
+.BR keyctl (2),
+.BR keyctl_invalidate (3)