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 libc, 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 libc 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.