.\"	$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 2, 2014
.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;
.It COMPAT
a compatibility system call, only included if the corresponding
option is configured for the kernel.
.El
.El
.Pp
The rest of the line for the STD, NODEF, NOARGS, and COMPAT
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,
.Li make sysent
has to be run from the directory containing the
.Dq master
file.
Please mind that the string
.Li sys_
is prepended to all system call names, but not to the structures
holding the arguments.
So, if one has added the line:
.Bd -literal
503	STD	BSD	{ int mycall(int x, int y); }
.Ed
.Pp
to the system call master file, the generated prototype would be:
.Pp
.Ft int
.Fn sys_mycall "struct mycall_args *uap" ;
.Pp
It is customary to extract system call arguments with the
.Fn SCARG uap member
macro, which is defined in
.Pa sys/sys/sysent.h
file.
Last, in order to return a value to userland, the
.Fa uap->sysmsg_result
variable and friends of it are used, as defined in
.Pa sys/sys/sysmsg.h .
.Sh IMPLEMENTATION NOTES
In the kernel, a syscall is implemented by a
.Fn sys_syscallname
function.
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/{i386,x86_64} ,
again using the description in
.Pa syscalls.master .
These wrappers use macros provided by the platform-dependent
.In SYS.h
header file which take care of putting the syscall arguments into registers
(per the ABI specification) and either invoking int 0x80 (on i386) or
inserting a
.Li syscall
instruction (on x86_64).
.Sh FILES
.Bl -tag -width sys/kern/syscalls.master -compact
.It Pa sys/kern/makesyscalls.sh
a
.Xr sh 1
script for generating C files out of the syscall master file;
.It Pa sys/kern/syscalls.conf
a configuration file for the shell script above;
.It Pa sys/kern/syscalls.master
master files describing names and numbers for the system calls;
.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/sysproto.h
system call argument lists;
.It Pa sys/sys/syscall.h
system call numbers.
.It Pa sys/emulation/linux/i386
Linux emulation system calls.
.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 .