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 May 22, 2020 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.Li make sysent 100has to be run from the directory containing the 101.Dq master 102file. 103Please mind that the string 104.Li sys_ 105is prepended to all system call names, but not to the structures 106holding the arguments. 107So, if one has added the line: 108.Bd -literal 109503 STD BSD { int mycall(int x, int y); } 110.Ed 111.Pp 112to the system call master file, the generated prototype would be: 113.Pp 114.Ft int 115.Fn sys_mycall "struct mycall_args *uap" ; 116.Pp 117It is customary to extract system call arguments with the 118.Fn SCARG uap member 119macro, which is defined in 120.Pa sys/sys/sysent.h 121file. 122.Pp 123Any value which the 124.Fn sys_mycall 125kernel function returns ends up in 126.Va errno 127after executing the 128.Fn mycall 129libc function, and the return value of 130.Fn mycall 131is automatically -1 or 0 depending on whether 132.Va errno 133was set or not. 134A function that needs to return a different value to userland, e.g.\& a 135file descriptor, must override the default value in 136.Fa uap->sysmsg_result , 137as defined in 138.Pa sys/sys/sysmsg.h . 139.Sh IMPLEMENTATION NOTES 140In the kernel, a syscall is implemented by a 141.Fn sys_syscallname 142function. 143In userspace, the function that executes a syscall is automatically generated 144using the description in 145.Pa syscalls.master . 146The symbols in the 147.Lb libc 148are assembly wrappers generated in 149.Pa lib/libc/${MACHINE_ARCH} Pq e.g.\& x86_64 , 150again using the description in 151.Pa syscalls.master . 152These wrappers use macros provided by the platform-dependent 153.In SYS.h 154header file which take care of putting the syscall arguments into registers 155(per the ABI specification) and inserting a 156.Li syscall 157instruction (on x86_64). 158.Sh FILES 159.Bl -tag -width sys/kern/syscalls.master -compact 160.It Pa sys/kern/makesyscalls.sh 161a 162.Xr sh 1 163script for generating C files out of the syscall master file; 164.It Pa sys/kern/syscalls.conf 165a configuration file for the shell script above; 166.It Pa sys/kern/syscalls.master 167master files describing names and numbers for the system calls; 168.It Pa sys/kern/syscalls.c 169system call names lists; 170.It Pa sys/kern/init_sysent.c 171system call switch tables; 172.It Pa sys/sys/sysproto.h 173system call argument lists; 174.It Pa sys/sys/syscall.h 175system call numbers. 176.El 177.Sh SEE ALSO 178.Xr ktrace 2 , 179.Xr syscall 2 , 180.Xr SYSCALL_MODULE 9 181.Sh HISTORY 182The 183.Nm 184section manual page appeared in 185.Dx 2.3 . 186