.\"	$OpenBSD: syscall.9,v 1.7 2007/05/31 19:20:01 jmc Exp $
.\"
.\" Copyright (c) 2003 Michael Shalayeff
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF MIND, USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd January 19, 2021
.Dt SYSCALL 9
.Os
.Sh NAME
.Nm syscall
.Nd system calls overview
.Sh DESCRIPTION
A system call is an explicit request to the kernel made via a software
interrupt by some program.
For example,
.Fn open
is a system call that is used when access to a file stored in filesystem
is needed.
In this sense, system calls provide the interface between a process and the
operating system.
.Pp
The kernel implements system calls through a set of switch tables
for each emulation type.
The list of currently supported system calls along with their codes resides in
.Pa sys/sys/syscall.h .
This file, and a couple others which will be examined later, are
automatically generated and should not be edited manually.
.Pp
The first step in adding a new system call is to edit the
.Pa sys/kern/syscalls.master
file.
The
.Dq master
file is a text file consisting of a list of lines for each
system call.
Lines may be split by the means of back slashing the end of the line.
Each line is a set of fields separated by whitespace:
.Pp
.D1 Cd number type ...
.Pp
Where:
.Bl -tag -width number -compact
.It number
is the system call number;
.It type
is one of:
.Bl -tag -width NOPROTO -compact
.It STD
standard system call with full prototype and implementation;
.It OBSOL
obsolete, not included in the system;
.It UNIMPL
unimplemented, not included in the system, placeholder only;
.It NODEF
included, but don't define the syscall number;
.It NOARGS
included, but don't define the syscall args structure;
.It NOPROTO
implemented elsewhere;
.El
.El
.Pp
The rest of the line for the STD, NODEF, and NOARGS types is:
.Pp
.D1 Cd { pseudo-proto } [alias]
.Pp
.Nm pseudo-proto
is a C-like prototype used to generate the system call argument list,
and alias is an optional name alias for the call.
The function in the prototype has to be defined somewhere in
the kernel sources as it will be used as an entry point for
the corresponding system call.
.Pp
For other types the rest of the line is a comment.
.Pp
To generate the header and code files from the
.Dq master
file,
.Cm make sysent
has to be run from the directory containing the
.Dq master
file.
Please mind that the string
.Dq sys_
is prepended to all system call names, but not to the structures
holding the arguments.
So, if one has added this line to the system call
.Dq master
file:
.Bd -literal
503	STD	{ int mycall(int x, int y); }
.Ed
.Pp
the generated prototype would be:
.Pp
.Ft int
.Fn sys_mycall "struct sysmsg *sysmsg" "const struct mycall_args *uap" ;
.Pp
Any value that the
.Fn sys_mycall
kernel function returns ends up in
.Va errno
after executing the
.Fn mycall
libc function, and the return value of
.Fn mycall
is automatically -1 or 0 depending on whether
.Va errno
was set or not.
A function that needs to return a different value to userland, e.g.\& a
file descriptor, must override the default value in
.Fa sysmsg->sysmsg_result
(as defined in
.Pa sys/sys/sysmsg.h )
and return 0.
.Pp
In the
.Lb libc ,
the assembly wrapper (as described below) will create these symbols:
.Sy mycall ,
.Sy _mycall
and
.Sy __sys_mycall .
To export the syscall for external use, add symbol
.Sy mycall
to the appropriate
.Dv DFxxx.0
section in the
.Pa lib/libc/sys/Symbol.map
file.
In addition, add symbols
.Sy _mycall
and
.Sy __sys_mycall
to the
.Dv DFprivate_1.0
section in the same file for internal use.
.Sh IMPLEMENTATION NOTES
In the kernel, the syscall entry point is implemented in platform-dependent
assembly code (e.g.,
.Pa sys/platform/pc64/x86_64/exception.S
for x86_64 machines),
and the syscall itself is implemented by a
.Fn sys_syscallname
function.
.Pp
In userspace, the function that executes a syscall is automatically generated
using the description in
.Pa syscalls.master .
The symbols in the
.Lb libc
are assembly wrappers generated in
.Pa lib/libc/${MACHINE_ARCH}
.Pq e.g.\& x86_64 ,
again using the description in
.Pa syscalls.master .
These wrappers use macros provided by the platform-dependent
.Pa SYS.h
header file which take care of putting the syscall arguments into registers
(per the ABI specification) and inserting a
.Li syscall
instruction (on x86_64).
.Sh FILES
.Bl -tag -width sys/kern/syscalls.master -compact
.It Pa sys/kern/syscalls.master
the
.Dq master
file describing names and numbers for the system calls;
.It Pa sys/kern/makesyscalls.sh
a
.Xr sh 1
script for generating C files out of the syscall master file above;
.It Pa sys/kern/syscalls.c
system call names lists;
.It Pa sys/kern/init_sysent.c
system call switch tables;
.It Pa sys/sys/syscall.h
system call numbers;
.It Pa sys/sys/sysmsg.h
system call message structure;
.It Pa sys/sys/sysproto.h
system call argument lists;
.It Pa sys/sys/sysunion.h
system call argument union.
.El
.Sh SEE ALSO
.Xr ktrace 2 ,
.Xr syscall 2 ,
.Xr SYSCALL_MODULE 9
.Sh HISTORY
The
.Nm
section manual page appeared in
.Dx 2.3 .