1.\" $OpenBSD: syscall.9,v 1.7 2007/05/31 19:20:01 jmc Exp $ 2.\" 3.\" Copyright (c) 2003 Michael Shalayeff 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 13.\" 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 24.\" SUCH DAMAGE. 25.\" 26.Dd January 19, 2021 27.Dt SYSCALL 9 28.Os 29.Sh NAME 30.Nm syscall 31.Nd system calls overview 32.Sh DESCRIPTION 33A system call is an explicit request to the kernel made via a software 34interrupt by some program. 35For example, 36.Fn open 37is a system call that is used when access to a file stored in filesystem 38is needed. 39In this sense, system calls provide the interface between a process and the 40operating system. 41.Pp 42The kernel implements system calls through a set of switch tables 43for each emulation type. 44The list of currently supported system calls along with their codes resides in 45.Pa sys/sys/syscall.h . 46This file, and a couple others which will be examined later, are 47automatically generated and should not be edited manually. 48.Pp 49The first step in adding a new system call is to edit the 50.Pa sys/kern/syscalls.master 51file. 52The 53.Dq master 54file is a text file consisting of a list of lines for each 55system call. 56Lines may be split by the means of back slashing the end of the line. 57Each line is a set of fields separated by whitespace: 58.Pp 59.D1 Cd number type ... 60.Pp 61Where: 62.Bl -tag -width number -compact 63.It number 64is the system call number; 65.It type 66is one of: 67.Bl -tag -width NOPROTO -compact 68.It STD 69standard system call with full prototype and implementation; 70.It OBSOL 71obsolete, not included in the system; 72.It UNIMPL 73unimplemented, not included in the system, placeholder only; 74.It NODEF 75included, but don't define the syscall number; 76.It NOARGS 77included, but don't define the syscall args structure; 78.It NOPROTO 79implemented elsewhere; 80.El 81.El 82.Pp 83The rest of the line for the STD, NODEF, and NOARGS types is: 84.Pp 85.D1 Cd { pseudo-proto } [alias] 86.Pp 87.Nm pseudo-proto 88is a C-like prototype used to generate the system call argument list, 89and alias is an optional name alias for the call. 90The function in the prototype has to be defined somewhere in 91the kernel sources as it will be used as an entry point for 92the corresponding system call. 93.Pp 94For other types the rest of the line is a comment. 95.Pp 96To generate the header and code files from the 97.Dq master 98file, 99.Cm make sysent 100has to be run from the directory containing the 101.Dq master 102file. 103Please mind that the string 104.Dq sys_ 105is prepended to all system call names, but not to the structures 106holding the arguments. 107So, if one has added this line to the system call 108.Dq master 109file: 110.Bd -literal 111503 STD { int mycall(int x, int y); } 112.Ed 113.Pp 114the generated prototype would be: 115.Pp 116.Ft int 117.Fn sys_mycall "struct sysmsg *sysmsg" "const struct mycall_args *uap" ; 118.Pp 119Any value that the 120.Fn sys_mycall 121kernel function returns ends up in 122.Va errno 123after executing the 124.Fn mycall 125libc function, and the return value of 126.Fn mycall 127is automatically -1 or 0 depending on whether 128.Va errno 129was set or not. 130A function that needs to return a different value to userland, e.g.\& a 131file descriptor, must override the default value in 132.Fa sysmsg->sysmsg_result 133(as defined in 134.Pa sys/sys/sysmsg.h ) 135and return 0. 136.Pp 137In the 138.Lb libc , 139the assembly wrapper (as described below) will create these symbols: 140.Sy mycall , 141.Sy _mycall 142and 143.Sy __sys_mycall . 144To export the syscall for external use, add symbol 145.Sy mycall 146to the appropriate 147.Dv DFxxx.0 148section in the 149.Pa lib/libc/sys/Symbol.map 150file. 151In addition, add symbols 152.Sy _mycall 153and 154.Sy __sys_mycall 155to the 156.Dv DFprivate_1.0 157section in the same file for internal use. 158.Sh IMPLEMENTATION NOTES 159In the kernel, the syscall entry point is implemented in platform-dependent 160assembly code (e.g., 161.Pa sys/platform/pc64/x86_64/exception.S 162for x86_64 machines), 163and the syscall itself is implemented by a 164.Fn sys_syscallname 165function. 166.Pp 167In userspace, the function that executes a syscall is automatically generated 168using the description in 169.Pa syscalls.master . 170The symbols in the 171.Lb libc 172are assembly wrappers generated in 173.Pa lib/libc/${MACHINE_ARCH} 174.Pq e.g.\& x86_64 , 175again using the description in 176.Pa syscalls.master . 177These wrappers use macros provided by the platform-dependent 178.Pa SYS.h 179header file which take care of putting the syscall arguments into registers 180(per the ABI specification) and inserting a 181.Li syscall 182instruction (on x86_64). 183.Sh FILES 184.Bl -tag -width sys/kern/syscalls.master -compact 185.It Pa sys/kern/syscalls.master 186the 187.Dq master 188file describing names and numbers for the system calls; 189.It Pa sys/kern/makesyscalls.sh 190a 191.Xr sh 1 192script for generating C files out of the syscall master file above; 193.It Pa sys/kern/syscalls.c 194system call names lists; 195.It Pa sys/kern/init_sysent.c 196system call switch tables; 197.It Pa sys/sys/syscall.h 198system call numbers; 199.It Pa sys/sys/sysmsg.h 200system call message structure; 201.It Pa sys/sys/sysproto.h 202system call argument lists; 203.It Pa sys/sys/sysunion.h 204system call argument union. 205.El 206.Sh SEE ALSO 207.Xr ktrace 2 , 208.Xr syscall 2 , 209.Xr SYSCALL_MODULE 9 210.Sh HISTORY 211The 212.Nm 213section manual page appeared in 214.Dx 2.3 . 215