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 September 17, 2015 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. 126Last, in order to return a value to userland, the 127.Fa uap->sysmsg_result 128variable and friends of it are used, as defined in 129.Pa sys/sys/sysmsg.h . 130.Sh IMPLEMENTATION NOTES 131In the kernel, a syscall is implemented by a 132.Fn sys_syscallname 133function. 134In userspace, the function that executes a syscall is automatically generated 135using the description in 136.Pa syscalls.master . 137The symbols in the 138.Lb libc 139are assembly wrappers generated in 140.Pa lib/libc/${MACHINE_ARCH} Pq e.g.\& x86_64 , 141again using the description in 142.Pa syscalls.master . 143These wrappers use macros provided by the platform-dependent 144.In SYS.h 145header file which take care of putting the syscall arguments into registers 146(per the ABI specification) and inserting a 147.Li syscall 148instruction (on x86_64). 149.Sh FILES 150.Bl -tag -width sys/kern/syscalls.master -compact 151.It Pa sys/kern/makesyscalls.sh 152a 153.Xr sh 1 154script for generating C files out of the syscall master file; 155.It Pa sys/kern/syscalls.conf 156a configuration file for the shell script above; 157.It Pa sys/kern/syscalls.master 158master files describing names and numbers for the system calls; 159.It Pa sys/kern/syscalls.c 160system call names lists; 161.It Pa sys/kern/init_sysent.c 162system call switch tables; 163.It Pa sys/sys/sysproto.h 164system call argument lists; 165.It Pa sys/sys/syscall.h 166system call numbers. 167.\".It Pa sys/emulation/linux/i386 168.\"Linux emulation system calls. 169.El 170.Sh SEE ALSO 171.Xr ktrace 2 , 172.Xr syscall 2 , 173.Xr SYSCALL_MODULE 9 174.Sh HISTORY 175The 176.Nm 177section manual page appeared in 178.Dx 2.3 . 179