DragonFly On-Line Manual Pages
SYSCALL(9) DragonFly Kernel Developer's Manual SYSCALL(9)
NAME
syscall - system calls overview
DESCRIPTION
A system call is an explicit request to the kernel made via a software
interrupt by some program. For example, 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.
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 sys/sys/syscall.h. This file, and a couple
others which will be examined later, are automatically generated and
should not be edited manually.
The first step in adding a new system call is to edit the
sys/kern/syscalls.master file. The "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:
number type ...
Where:
number is the system call number;
type is one of:
STD standard system call with full prototype and
implementation;
OBSOL obsolete, not included in the system;
UNIMPL unimplemented, not included in the system, placeholder
only;
NODEF included, but don't define the syscall number;
NOARGS included, but don't define the syscall args structure;
NOPROTO implemented elsewhere;
The rest of the line for the STD, NODEF, and NOARGS types is:
{ pseudo-proto } [alias]
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.
For other types the rest of the line is a comment.
To generate the header and code files from the "master" file, make sysent
has to be run from the directory containing the "master" file. Please
mind that the string "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 "master" file:
503 STD { int mycall(int x, int y); }
the generated prototype would be:
int sys_mycall(struct sysmsg *sysmsg, const struct mycall_args *uap);
Any value that the sys_mycall() kernel function returns ends up in errno
after executing the mycall() libc function, and the return value of
mycall() is automatically -1 or 0 depending on whether 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
sysmsg->sysmsg_result (as defined in sys/sys/sysmsg.h) and return 0.
In the Standard C Library (libc, -lc), the assembly wrapper (as described
below) will create these symbols: mycall, _mycall and __sys_mycall. To
export the syscall for external use, add symbol mycall to the appropriate
DFxxx.0 section in the lib/libc/sys/Symbol.map file. In addition, add
symbols _mycall and __sys_mycall to the DFprivate_1.0 section in the same
file for internal use.
IMPLEMENTATION NOTES
In the kernel, the syscall entry point is implemented in platform-
dependent assembly code (e.g., sys/platform/pc64/x86_64/exception.S for
x86_64 machines), and the syscall itself is implemented by a
sys_syscallname() function.
In userspace, the function that executes a syscall is automatically
generated using the description in syscalls.master. The symbols in the
Standard C Library (libc, -lc) are assembly wrappers generated in
lib/libc/${MACHINE_ARCH} (e.g. x86_64), again using the description in
syscalls.master. These wrappers use macros provided by the platform-
dependent SYS.h header file which take care of putting the syscall
arguments into registers (per the ABI specification) and inserting a
syscall instruction (on x86_64).
FILES
sys/kern/syscalls.master the "master" file describing names and numbers
for the system calls;
sys/kern/makesyscalls.sh a sh(1) script for generating C files out of
the syscall master file above;
sys/kern/syscalls.c system call names lists;
sys/kern/init_sysent.c system call switch tables;
sys/sys/syscall.h system call numbers;
sys/sys/sysmsg.h system call message structure;
sys/sys/sysproto.h system call argument lists;
sys/sys/sysunion.h system call argument union.
SEE ALSO
ktrace(2), syscall(2), SYSCALL_MODULE(9)
HISTORY
The syscall section manual page appeared in DragonFly 2.3.
DragonFly 6.1-DEVELOPMENT January 19, 2021 DragonFly 6.1-DEVELOPMENT