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