document upcoming pinsyscalls(2) system call

ok kettenis, some tweaks from jmc

2 files changed, 79 insertions, 3 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index f45b41ada0d..28f1ac72b48 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile.inc,v 1.174 2023/08/20 15:17:53 visa Exp $
+#	$OpenBSD: Makefile.inc,v 1.175 2023/12/11 00:34:24 deraadt Exp $
 #	$NetBSD: Makefile.inc,v 1.35 1995/10/16 23:49:07 jtc Exp $
 #	@(#)Makefile.inc	8.1 (Berkeley) 6/17/93
 
@@ -208,8 +208,8 @@ MAN+=	__get_tcb.2 __thrsigdivert.2 __thrsleep.2 _exit.2 accept.2 \
 	mimmutable.2 minherit.2 mkdir.2 mkfifo.2 mknod.2 mlock.2 \
 	mlockall.2 mmap.2 mount.2 mprotect.2 mquery.2 msyscall.2 msgctl.2 \
 	msgget.2 msgrcv.2 msgsnd.2 msync.2 munmap.2 nanosleep.2 \
-	nfssvc.2 open.2 pathconf.2 pinsyscall.2 pipe.2 pledge.2 poll.2 \
-	profil.2 ptrace.2 quotactl.2 read.2 readlink.2 reboot.2 recv.2 \
+	nfssvc.2 open.2 pathconf.2 pinsyscall.2 pinsyscalls.2 pipe.2 pledge.2 \
+	poll.2 profil.2 ptrace.2 quotactl.2 read.2 readlink.2 reboot.2 recv.2 \
 	rename.2 revoke.2 rmdir.2 sched_yield.2 select.2 semctl.2 semget.2 \
 	semop.2 send.2 setgroups.2 setpgid.2 setregid.2 \
 	setresuid.2 setreuid.2 setsid.2 sendsyslog.2 setuid.2 shmat.2 \
diff --git a/lib/libc/sys/pinsyscalls.2 b/lib/libc/sys/pinsyscalls.2
new file mode 100644
index 00000000000..bbbe4ab67d2
--- /dev/null
+++ b/lib/libc/sys/pinsyscalls.2
@@ -0,0 +1,76 @@
+.\" $OpenBSD: pinsyscalls.2,v 1.1 2023/12/11 00:34:24 deraadt Exp $
+.\"
+.\" Copyright (c) 2023 Theo de Raadt <deraadt@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" 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 $
+.Dt PINSYSCALLS 2
+.Os
+.Sh NAME
+.Nm pinsyscalls
+.Nd pin system call entry to precise locations in the address space
+.Sh SYNOPSIS
+.In sys/types.h
+.Ft int
+.Fn pinsyscalls "void *start" "size_t len" "uint *pintable" "size_t pintablesize"
+.Sh DESCRIPTION
+The
+.Fn pinsyscalls
+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.
+.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
+.Pa libc.so
+(the filename is actually /usr/lib/libc.so.major.minor).
+.Pp
+A similar setup operation is done automatically by the kernel for
+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 EINVAL
+Process already has a system call pinning table loaded.
+.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.
+.El
+.Sh HISTORY
+The
+.Fn pinsyscalls
+system call first appeared in
+.Ox 7.4 .