1.\" $OpenBSD: pinsyscalls.2,v 1.5 2024/04/01 19:29:16 benno Exp $ 2.\" 3.\" Copyright (c) 2023 Theo de Raadt <deraadt@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 1 2024 $ 18.Dt PINSYSCALLS 2 19.Os 20.Sh NAME 21.Nm pinsyscalls 22.Nd pin system call entry to precise locations in the address space 23.Sh SYNOPSIS 24.In sys/types.h 25.Ft int 26.Fn pinsyscalls "void *start" "size_t len" "u_int *pintable" "int npins" 27.Sh DESCRIPTION 28The 29.Fn pinsyscalls 30system call specifies the 31.Va start 32to 33.Va start + len 34address space range where the system call entry instructions are found, 35and a 36.Va npins Ns 37-sized array of u_int entries (indexed by the system call number) 38which are offsets from the 39.Va start . 40.Pp 41This provides the precise location for the system call instruction 42required for each system call number. 43Attempting to use a different system call entry instruction to perform 44a non-corresponding system call operation will fail with signal 45.Dv SIGABRT . 46.Pp 47.Fn pinsyscalls 48is only called by the shared library linker 49.Xr ld.so 1 50to tell the kernel where the text / executable region containing 51system calls is found in the dynamic library 52.Pa libc.so 53(the filename is actually /usr/lib/libc.so.major.minor). 54.Pp 55A similar setup operation is done automatically by the kernel for 56the system calls found in 57.Xr ld.so 1 58and in static executables. 59.Sh RETURN VALUES 60.Rv -std 61.Sh ERRORS 62.Fn pinsyscalls 63will fail if: 64.Bl -tag -width Er 65.It Bq Er E2BIG 66Implausible number of system calls provided. 67.It Bq Er ENOMEM 68Insufficient memory to service the request. 69.It Bq Er EPERM 70A static binary tried to call 71.Fn pinsyscalls , or it was called a second time. 72.It Bq Er ERANGE 73At least one system call offset is beyond the bounds of 74.Ar len . 75.El 76.Sh HISTORY 77The 78.Fn pinsyscalls 79system call first appeared in 80.Ox 7.5 . 81