1.\" $OpenBSD: kbind.2,v 1.4 2021/11/21 23:44:55 jan Exp $ 2.\" 3.\" Copyright (c) 2015 Philip Guenther <guenther@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: November 21 2021 $ 18.Dt KBIND 2 19.Os 20.Sh NAME 21.Nm kbind 22.Nd update protected memory for lazy-binding 23.Sh SYNOPSIS 24.In sys/unistd.h 25.Bd -literal 26struct __kbind { 27 void *kb_addr; 28 size_t kb_size; 29}; 30#define KBIND_BLOCK_MAX 2 /* powerpc and sparc64 need 2 blocks */ 31#define KBIND_DATA_MAX 24 /* sparc64 needs 6, four-byte words */ 32.Ed 33.Pp 34.Ft int 35.Fn kbind "const struct __kbind *param" "size_t psize" "int64_t cookie" 36.Sh DESCRIPTION 37The 38.Nm 39syscall updates the contents of one or more blocks of the process's memory 40with the supplied replacement data. 41This is used to efficiently and securely perform lazy-binding. 42.Pp 43.Fa param 44points to an array of 45.Vt __kbind 46structures giving the addresses and lengths to update. 47The last 48.Vt __kbind 49structure is immediately followed in the same order by the source 50data for the blocks to copy. 51.Fa psize 52specifies the total length of the parameters: both the 53.Vt __kbind 54structures and the associated source data. 55There may be at most 56.Dv KBIND_BLOCK_MAX 57.Vt __kbind 58structures and each block may be at most 59.Dv KBIND_DATA_MAX 60bytes in size. 61.Pp 62.Nm 63updates memory 64.Do 65as if 66.Dc 67the thread temporarily made the memory writable with 68.Xr mprotect 2 . 69If the process does not have write access to the underlying memory object, 70.Nm 71will fail without making the requested change. 72.Pp 73.Nm 74is currently intended for use by 75.Xr ld.so 1 76only. 77It is therefore not provided as a function and two security checks 78are performed to bind it (pun intended) to its use in 79.Xr ld.so 1 : 80the first time 81.Nm 82is used, the kernel records both the text address of the call and 83the value of the 84.Fa cookie 85argument. 86If those values differ in a later 87.Nm 88call, then the process is killed. 89.Sh RETURN VALUES 90.Rv -std 91.Sh ERRORS 92.Fn kbind 93will fail if: 94.Bl -tag -width Er 95.It Bq Er ENOMEM 96Cannot allocate memory when updating a copy-on-write page. 97.It Bq Er EINVAL 98The parameters are inconsistent or exceed 99.Nm 100limits. 101.It Bq Er EFAULT 102Part of the structures or additional data pointed to by 103.Fa param 104is outside the process's allocated address space, 105or the underlying memory object is not writable. 106.El 107.Sh SEE ALSO 108.Xr ld.so 1 , 109.Xr mprotect 2 110.Sh STANDARDS 111The 112.Nm 113syscall is specific to the 114.Ox 115dynamic linker and should not be used in portable applications. 116.Sh HISTORY 117The 118.Nm 119syscall appeared in 120.Ox 5.8 . 121