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.Dd February 10, 2018
26.Dt SYSCALL_HELPER_REGISTER 9
27.Os
28.Sh NAME
29.Nm syscall_helper_register ,
30.Nm syscall_helper_unregister
31.Nd kernel syscall registration routines
32.\"
33.Sh SYNOPSIS
34.In sys/sysent.h
35.Ft int
36.Fn syscall_helper_register "struct syscall_helper_data *sd" "int flags"
37.Ft int
38.Fn syscall_helper_unregister "struct syscall_helper_data *sd"
39.\"
40.Ss INITIALIZER MACROS
41.Ft struct syscall_helper_data
42.Fn SYSCALL_INIT_HELPER "syscallname"
43.Ft struct syscall_helper_data
44.Fn SYSCALL_INIT_HELPER_F "syscallname" "int flags"
45.\"
46.Ss COMPATIBILITY INITIALIZER MACROS
47.Ft struct syscall_helper_data
48.Fn SYSCALL_INIT_HELPER_COMPAT "syscallname"
49.Ft struct syscall_helper_data
50.Fn SYSCALL_INIT_HELPER_COMPAT_F "syscallname" "int flags"
51.\"
52.Sh DESCRIPTION
53The
54.Fn syscall_helper_register
55registers a system call.
56This function takes the structure
57.Va struct syscall_helper_data sd ,
58which specifies the parameters for syscall registration:
59.Pp
60.Bd -literal -offset indent -compact
61struct syscall_helper_data {
62	struct sysent	new_sysent;
63	struct sysent	old_sysent;
64	int		syscall_no;
65	int		registered;
66};
67.Ed
68.Pp
69The only valid flag for the
70.Fa flags
71argument to
72.Fn syscall_helper_register
73is
74.Dv SY_THR_STATIC .
75This flag prevents the syscall from being unregistered.
76.\"
77.Pp
78Before use, the structure must be initialized with one of the
79.Fn SYSCALL_INIT_HELPER*
80macros.
81In new code, syscall implementation functions shall be named
82.Fn sys_syscallname
83and the regular macros shall be used.
84.Pp
85For legacy syscall functions named without "sys_" prefixes, the "COMPAT"
86versions of the macros may be used.
87.Pp
88The only valid flag for the
89.Fa flags
90argument to the "F" variants of the initializer macros is
91.Dv SYF_CAPENABLED .
92This flag indicates that the syscall is allowed in capability mode.
93.Pp
94The
95.Fn syscall_helper_unregister
96unregisters a system call.
97This function takes the same structure
98.Va struct syscall_helper_data sd
99that was previously initialized in the manner described above and used in a
100successful invocation of
101.Fn syscall_helper_register .
102.\"
103.Sh RETURN VALUES
104If successful,
105.Fn syscall_helper_register
106and
107.Fn syscall_helper_unregister
108will return 0.
109Otherwise, they will return an error.
110.\"
111.Sh ERRORS
112The
113.Fn syscall_helper_register
114call will fail and the syscall will not be registered if:
115.Bl -tag -width Er
116.It Bq Er EINVAL
117The
118.Fa flags
119argument contained a value other than
120.Dv SY_THR_STATIC .
121.It Bq Er EINVAL
122The specified syscall number,
123.Dv sd.syscall_no
124.Dv ( SYS_syscallname ) ,
125was outside of the valid range of system call numbers (zero through
126.Dv SYS_MAXSYSCALL ) .
127.It Bq Er ENFILE
128The system call table does not have any available slots.
129.It Bq Er EEXIST
130The specified syscall number,
131.Dv sd.syscall_no
132.Dv ( SYS_syscallname ) ,
133was already in use.
134.El
135.\"
136.Sh SEE ALSO
137.Xr SYSCALL_MODULE 9
138