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