1 .\" $OpenBSD: syscall.9,v 1.7 2007/05/31 19:20:01 jmc Exp $
3 .\" Copyright (c) 2003 Michael Shalayeff
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF MIND, USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .Dd September 17, 2015
31 .Nd "system calls overview"
33 A system call is an explicit request to the kernel made via a software
34 interrupt by some program.
37 is a system call that is used when access to a file stored in filesystem
39 In this sense, system calls provide the interface between a process and the
42 The kernel implements system calls through a set of switch tables
43 for each emulation type.
44 The list of currently supported system calls along with their codes resides in
45 .Pa sys/sys/syscall.h .
46 This file, and a couple others which will be examined later, are
47 automatically generated and should not be edited manually.
49 The first step in adding a new system call is to edit the
50 .Pa sys/kern/syscalls.master
54 file is a text file consisting of a list of lines for each
56 Lines may be split by the means of back slashing the end of the line.
57 Each line is a set of fields separated by whitespace:
59 .D1 Cd number type ...
62 .Bl -tag -width number -compact
64 is the system call number;
67 .Bl -tag -width NOPROTO -compact
69 standard system call with full prototype and implementation;
71 obsolete, not included in the system;
73 unimplemented, not included in the system, placeholder only;
75 included, but don't define the syscall number;
77 included, but don't define the syscall args structure;
79 implemented elsewhere;
81 a compatibility system call, only included if the corresponding
82 option is configured for the kernel.
86 The rest of the line for the STD, NODEF, NOARGS, and COMPAT
89 .D1 Cd { pseudo-proto } [alias]
92 is a C-like prototype used to generate the system call argument list,
93 and alias is an optional name alias for the call.
94 The function in the prototype has to be defined somewhere in
95 the kernel sources as it will be used as an entry point for
96 the corresponding system call.
98 For other types the rest of the line is a comment.
100 To generate the header and code files from the
104 has to be run from the directory containing the
107 Please mind that the string
109 is prepended to all system call names, but not to the structures
110 holding the arguments.
111 So, if one has added the line:
113 503 STD BSD { int mycall(int x, int y); }
116 to the system call master file, the generated prototype would be:
119 .Fn sys_mycall "struct mycall_args *uap" ;
121 It is customary to extract system call arguments with the
123 macro, which is defined in
126 Last, in order to return a value to userland, the
127 .Fa uap->sysmsg_result
128 variable and friends of it are used, as defined in
129 .Pa sys/sys/sysmsg.h .
130 .Sh IMPLEMENTATION NOTES
131 In the kernel, a syscall is implemented by a
134 In userspace, the function that executes a syscall is automatically generated
135 using the description in
136 .Pa syscalls.master .
139 are assembly wrappers generated in
140 .Pa lib/libc/${MACHINE_ARCH} Pq e.g.\& x86_64 ,
141 again using the description in
142 .Pa syscalls.master .
143 These wrappers use macros provided by the platform-dependent
145 header file which take care of putting the syscall arguments into registers
146 (per the ABI specification) and inserting a
148 instruction (on x86_64).
150 .Bl -tag -width sys/kern/syscalls.master -compact
151 .It Pa sys/kern/makesyscalls.sh
154 script for generating C files out of the syscall master file;
155 .It Pa sys/kern/syscalls.conf
156 a configuration file for the shell script above;
157 .It Pa sys/kern/syscalls.master
158 master files describing names and numbers for the system calls;
159 .It Pa sys/kern/syscalls.c
160 system call names lists;
161 .It Pa sys/kern/init_sysent.c
162 system call switch tables;
163 .It Pa sys/sys/sysproto.h
164 system call argument lists;
165 .It Pa sys/sys/syscall.h
175 section manual page appeared in