.\" $OpenBSD: pinsyscall.2,v 1.5 2023/02/21 19:49:50 jmc 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 21 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" "void *start" "size_t len"
.Sh DESCRIPTION
The
.Fn pinsyscall
system call specifies the
.Va start
to
.Va start + len
range in the address space 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.
For static binaries, libc initialization performs the same action.
.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 .