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 25, 2009 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 namespace ... 60.Pp 61Where: 62.Bl -tag -width namespace -compact 63.It number 64is the system call number; 65.It namespace 66is one of POSIX, BSD, NOHIDE; 67.It type 68is one of: 69.Bl -tag -width NOPROTO -compact 70.It STD 71standard system call with full prototype and implementation; 72.It OBSOL 73obsolete, not included in the system; 74.It UNIMPL 75unimplemented, not included in the system, placeholder only; 76.It NODEF 77included, but don't define the syscall number; 78.It NOARGS 79included, but don't define the syscall args structure; 80.It NOPROTO 81implemented elsewhere; 82.It COMPAT 83a compatibility system call, only included if the corresponding 84option is configured for the kernel. 85.El 86.El 87.Pp 88The rest of the line for the STD, NODEF, NOARGS, and COMPAT 89types is: 90.Pp 91.D1 Cd { pseudo-proto } [alias] 92.Pp 93.Nm pseudo-proto 94is a C-like prototype used to generate the system call argument list, 95and alias is an optional name alias for the call. 96The function in the prototype has to be defined somewhere in 97the kernel sources as it will be used as an entry point for 98the corresponding system call. 99.Pp 100For other types the rest of the line is a comment. 101.Pp 102To generate the header and code files from the 103.Dq master 104file, 105.Li make sysent 106has to be run from the directory containing the 107.Dq master 108file. 109Please mind that the string 110.Li sys_ 111is prepended to all system call names, but not to the structures 112holding the arguments. 113So, if one has added the line: 114.Bd -literal 115503 STD BSD { int mycall(int x, int y); } 116.Ed 117.Pp 118to the system call master file, the generated prototype would be: 119.Pp 120.Ft int 121.Fn sys_mycall "struct mycall_args *uap" ; 122.Pp 123It is customary to extract system call arguments with the 124.Fn SCARG uap member 125macro, which is defined in 126.Pa sys/sys/sysent.h 127file. 128Last, in order to return a value to userland, the 129.Fa uap->sysmsg_result 130variable and friends of it are used, as defined in 131.Pa sys/sys/sysmsg.h . 132.Sh FILES 133.Bl -tag -width sys/kern/syscalls.master -compact 134.It Pa sys/kern/makesyscalls.sh 135a 136.Xr sh 1 137script for generating C files out of the syscall master file; 138.It Pa sys/kern/syscalls.conf 139a configuration file for the shell script above; 140.It Pa sys/kern/syscalls.master 141master files describing names and numbers for the system calls; 142.It Pa sys/kern/syscalls.c 143system call names lists; 144.It Pa sys/kern/init_sysent.c 145system call switch tables; 146.It Pa sys/sys/sysproto.h 147system call argument lists; 148.It Pa sys/sys/syscall.h 149system call numbers. 150.It Pa sys/emulation/linux/i386 151Linux emulation system calls. 152.El 153.Sh SEE ALSO 154.Xr ktrace 2 , 155.Xr syscall 2 , 156.Xr SYSCALL_MODULE 9 157.Sh HISTORY 158The 159.Nm 160section manual page appeared in 161.Dx 2.3 . 162