From: deraadt <deraadt@openbsd.org>
Date: Thu, 16 Feb 2023 04:43:54 +0000 (+0000)
Subject: Document pinsyscall(2).  The ld.so and kernel enforcement code is not
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=810f6e8b706d25bb8efcef3c9d4529fa4a6949a7;p=openbsd

Document pinsyscall(2).  The ld.so and kernel enforcement code is not
commited ye -- waiting for enough people to run kernels which support
the system call.
ok jmc
---

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index f359b3e07b7..f5230972104 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile.inc,v 1.170 2023/02/11 23:07:28 deraadt Exp $
+#	$OpenBSD: Makefile.inc,v 1.171 2023/02/16 04:43:54 deraadt Exp $
 #	$NetBSD: Makefile.inc,v 1.35 1995/10/16 23:49:07 jtc Exp $
 #	@(#)Makefile.inc	8.1 (Berkeley) 6/17/93
 
@@ -191,8 +191,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 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 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/pinsyscall.2 b/lib/libc/sys/pinsyscall.2
new file mode 100644
index 00000000000..4c4f7d0a82f
--- /dev/null
+++ b/lib/libc/sys/pinsyscall.2
@@ -0,0 +1,79 @@
+.\" $OpenBSD: pinsyscall.2,v 1.1 2023/02/16 04:43:54 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: February 16 2023 $
+.Dt PINSYSCALL 2
+.Os
+.Sh NAME
+.Nm pinsyscall
+.Nd specify the call stub for a specific system call
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/syscall.h
+.Ft int
+.Fn pinsyscall "int syscall" "char *start" "size_t len"
+.Sh DESCRIPTION
+The
+.Fn pinsyscall
+system call specifies the
+.Va start
+to
+.Va start + len
+range in the
+.Pa libc.so
+shared library where the call stub for the
+specified
+.Va syscall
+resides.
+This range is typically under 80 bytes long, and varies by architecture.
+.Pp
+Only the
+.Va SYS_execve
+system call is currently supported.
+The shared library linker
+.Pa ld.so
+automatically tells the kernel about
+.Va SYS_execve
+at startup.
+.Pp
+Once the kernel knows the specific location in the address space where
+that system call must be entered from, any attempt to use a system-call
+entry instruction to perform the specified
+.Va syscall
+from a different address range will deliver
+Dv SIGABRT .
+.Sh RETURN VALUES
+.Rv -std
+.Sh ERRORS
+.Fn pinsyscall
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+Unsupported syscall.
+.It Bq Er EFAULT
+The range between
+.Va start
+and
+.Va start + len
+is not in the address space.
+.It Bq Er EPERM
+The range for the specified syscall has been previously set.
+.El
+.Sh HISTORY
+The
+.Fn pinsyscall
+system call first appeared in
+.Ox 7.3 .