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. A long line may be
split into multiple lines by ending the lines with a backslash (`\').
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]
Where the pseudo-proto is a C-like prototype used to generate the system
call argument list, and the 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, run make
sysent from the sys/kern directory that contains the "master" file.
Please mind that the string "sys_" is prepended to all system call names,
but not to the structures holding the arguments. For example, 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 manual page appeared in DragonFly 2.3.
DragonFly 6.5-DEVELOPMENT March 16, 2025 DragonFly 6.5-DEVELOPMENT