1.\" Copyright (c) 2018 Conrad Meyer <cem@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd February 10, 2018 28.Dt SYSCALL_HELPER_REGISTER 9 29.Os 30.Sh NAME 31.Nm syscall_helper_register , 32.Nm syscall_helper_unregister 33.Nd kernel syscall registration routines 34.\" 35.Sh SYNOPSIS 36.In sys/sysent.h 37.Ft int 38.Fn syscall_helper_register "struct syscall_helper_data *sd" "int flags" 39.Ft int 40.Fn syscall_helper_unregister "struct syscall_helper_data *sd" 41.\" 42.Ss INITIALIZER MACROS 43.Ft struct syscall_helper_data 44.Fn SYSCALL_INIT_HELPER "syscallname" 45.Ft struct syscall_helper_data 46.Fn SYSCALL_INIT_HELPER_F "syscallname" "int flags" 47.\" 48.Ss COMPATIBILITY INITIALIZER MACROS 49.Ft struct syscall_helper_data 50.Fn SYSCALL_INIT_HELPER_COMPAT "syscallname" 51.Ft struct syscall_helper_data 52.Fn SYSCALL_INIT_HELPER_COMPAT_F "syscallname" "int flags" 53.\" 54.Sh DESCRIPTION 55The 56.Fn syscall_helper_register 57registers a system call. 58This function takes the structure 59.Va struct syscall_helper_data sd , 60which specifies the parameters for syscall registration: 61.Pp 62.Bd -literal -offset indent -compact 63struct syscall_helper_data { 64 struct sysent new_sysent; 65 struct sysent old_sysent; 66 int syscall_no; 67 int registered; 68}; 69.Ed 70.Pp 71The only valid flag for the 72.Fa flags 73argument to 74.Fn syscall_helper_register 75is 76.Dv SY_THR_STATIC . 77This flag prevents the syscall from being unregistered. 78.\" 79.Pp 80Before use, the structure must be initialized with one of the 81.Fn SYSCALL_INIT_HELPER* 82macros. 83In new code, syscall implementation functions shall be named 84.Fn sys_syscallname 85and the regular macros shall be used. 86.Pp 87For legacy syscall functions named without "sys_" prefixes, the "COMPAT" 88versions of the macros may be used. 89.Pp 90The only valid flag for the 91.Fa flags 92argument to the "F" variants of the initializer macros is 93.Dv SYF_CAPENABLED . 94This flag indicates that the syscall is allowed in capability mode. 95.Pp 96The 97.Fn syscall_helper_unregister 98unregisters a system call. 99This function takes the same structure 100.Va struct syscall_helper_data sd 101that was previously initialized in the manner described above and used in a 102successful invocation of 103.Fn syscall_helper_register . 104.\" 105.Sh RETURN VALUES 106If successful, 107.Fn syscall_helper_register 108and 109.Fn syscall_helper_unregister 110will return 0. 111Otherwise, they will return an error. 112.\" 113.Sh ERRORS 114The 115.Fn syscall_helper_register 116call will fail and the syscall will not be registered if: 117.Bl -tag -width Er 118.It Bq Er EINVAL 119The 120.Fa flags 121argument contained a value other than 122.Dv SY_THR_STATIC . 123.It Bq Er EINVAL 124The specified syscall number, 125.Dv sd.syscall_no 126.Dv ( SYS_syscallname ) , 127was outside of the valid range of system call numbers (zero through 128.Dv SYS_MAXSYSCALL ) . 129.It Bq Er ENFILE 130The system call table does not have any available slots. 131.It Bq Er EEXIST 132The specified syscall number, 133.Dv sd.syscall_no 134.Dv ( SYS_syscallname ) , 135was already in use. 136.El 137.\" 138.Sh SEE ALSO 139.Xr SYSCALL_MODULE 9 140