From d05290bad2bb4683202638fad1c97a530fabffbc Mon Sep 17 00:00:00 2001
From: deraadt <deraadt@openbsd.org>
Date: Tue, 19 Dec 2023 06:57:12 +0000
Subject: [PATCH] pinsyscalls(2) has changed a little bit, and I can provide
 more advice for how it is used (in ld.so, it's not like anyone else can call
 it). Also document the errors..

---
 lib/libc/sys/pinsyscalls.2 | 39 ++++++++++++++++++++++----------------
 1 file changed, 23 insertions(+), 16 deletions(-)

diff --git a/lib/libc/sys/pinsyscalls.2 b/lib/libc/sys/pinsyscalls.2
index bbbe4ab67d2..9a7acea8b7c 100644
--- a/lib/libc/sys/pinsyscalls.2
+++ b/lib/libc/sys/pinsyscalls.2
@@ -1,4 +1,4 @@
-.\" $OpenBSD: pinsyscalls.2,v 1.1 2023/12/11 00:34:24 deraadt Exp $
+.\" $OpenBSD: pinsyscalls.2,v 1.2 2023/12/19 06:57:12 deraadt Exp $
 .\"
 .\" Copyright (c) 2023 Theo de Raadt <deraadt@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: December 11 2023 $
+.Dd $Mdocdate: December 19 2023 $
 .Dt PINSYSCALLS 2
 .Os
 .Sh NAME
@@ -23,7 +23,7 @@
 .Sh SYNOPSIS
 .In sys/types.h
 .Ft int
-.Fn pinsyscalls "void *start" "size_t len" "uint *pintable" "size_t pintablesize"
+.Fn pinsyscalls "void *start" "size_t len" "u_int *pintable" "int npins"
 .Sh DESCRIPTION
 The
 .Fn pinsyscalls
@@ -31,17 +31,24 @@ system call specifies the
 .Va start
 to
 .Va start + len
-range in the address space where the system call entry instructions are found,
-and furthermore provides a table of uint offsets from that
-.Va start
-(indexed by the system call number) to
-provide the precise location for the system call instruction required
-for that system call number.
+address space range where the system call entry instructions are found,
+and a
+.Va npins Ns
+-sized array of u_int entries (indexed by the system call number)
+which are offsets from the
+.Va start .
+.Pp
+This provides the precise location for the system call instruction
+required for each system call number.  Attempting to use a different
+system call entry instruction to perform a non-corresponding system call
+operation will fail with signal
+.Dv SIGABRT .
 .Pp
 .Fn pinsyscalls
 is only called by the shared library linker
 .Xr ld.so 1
-to tell the kernel where system calls are found in the dynamic library
+to tell the kernel where the text / executable region containing
+system calls is found in the dynamic library
 .Pa libc.so
 (the filename is actually /usr/lib/libc.so.major.minor).
 .Pp
@@ -50,24 +57,24 @@ the system calls found in
 .Xr ld.so 1
 and in static executables.
 .Pp
-Once the kernel knows the specific location in the address space where
-a specific system call must be entered from, any attempt to use a different
-system call entry instruction to perform a non-corresponding system call
-operation will fail with signal
-.Dv SIGABRT .
 .Sh RETURN VALUES
 .Rv -std
 .Sh ERRORS
 .Fn pinsyscalls
 will fail if:
 .Bl -tag -width Er
+.It Bq Er E2BIG
+Implausible number of system calls provided.
 .It Bq Er EINVAL
 Process already has a system call pinning table loaded.
+.It Bq Er ENOMEM
+Insufficient memory to service the request.
 .It Bq Er EPERM
 A static binary tried to call
 .Fn pinsyscalls .
 .It Bq Er ERANGE
-At least one system call offset is out of bounds.
+At least one system call offset is beyond the bounds of
+.Ar len .
 .El
 .Sh HISTORY
 The
-- 
2.20.1