DragonFly On-Line Manual Pages

Search: Section:  

SYSCALL(9)            DragonFly Kernel Developer's Manual           SYSCALL(9)


syscall - system calls overview


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.


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).


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.


ktrace(2), syscall(2), SYSCALL_MODULE(9)


The syscall section manual page appeared in DragonFly 2.3. DragonFly 6.1-DEVELOPMENT January 19, 2021 DragonFly 6.1-DEVELOPMENT

Search: Section: