share/man/man9/syscall.9

   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
  33 A system call is an explicit request to the kernel made via a software
  34 interrupt by some program.
  35 For example,
  36 .Fn open
  37 is a system call that is used when access to a file stored in filesystem
  38 is needed.
  39 In this sense, system calls provide the interface between a process and the
  40 operating system.
  41 .Pp
  42 The kernel implements system calls through a set of switch tables
  43 for each emulation type.
  44 The list of currently supported system calls along with their codes resides in
  45 .Pa sys/sys/syscall.h .
  46 This file, and a couple others which will be examined later, are
  47 automatically generated and should not be edited manually.
  48 .Pp
  49 The first step in adding a new system call is to edit the
  50 .Pa sys/kern/syscalls.master
  51 file.
  52 The
  53 .Dq master
  54 file is a text file consisting of a list of lines for each
  55 system call.
  56 Lines may be split by the means of back slashing the end of the line.
  57 Each line is a set of fields separated by whitespace:
  58 .Pp
  59 .D1 Cd number type ...
  60 .Pp
  61 Where:
  62 .Bl -tag -width number -compact
  63 .It number
  64 is the system call number;
  65 .It type
  66 is one of:
  67 .Bl -tag -width NOPROTO -compact
  68 .It STD
  69 standard system call with full prototype and implementation;
  70 .It OBSOL
  71 obsolete, not included in the system;
  72 .It UNIMPL
  73 unimplemented, not included in the system, placeholder only;
  74 .It NODEF
  75 included, but don't define the syscall number;
  76 .It NOARGS
  77 included, but don't define the syscall args structure;
  78 .It NOPROTO
  79 implemented elsewhere;
  80 .It COMPAT
  81 a compatibility system call, only included if the corresponding
  82 option is configured for the kernel.
  83 .El
  84 .El
  85 .Pp
  86 The rest of the line for the STD, NODEF, NOARGS, and COMPAT
  87 types is:
  88 .Pp
  89 .D1 Cd { pseudo-proto } [alias]
  90 .Pp
  91 .Nm pseudo-proto
  92 is a C-like prototype used to generate the system call argument list,
  93 and alias is an optional name alias for the call.
  94 The function in the prototype has to be defined somewhere in
  95 the kernel sources as it will be used as an entry point for
  96 the corresponding system call.
  97 .Pp
  98 For other types the rest of the line is a comment.
  99 .Pp
 100 To generate the header and code files from the
 101 .Dq master
 102 file,
 103 .Li make sysent
 104 has to be run from the directory containing the
 105 .Dq master
 106 file.
 107 Please mind that the string
 108 .Li sys_
 109 is prepended to all system call names, but not to the structures
 110 holding the arguments.
 111 So, if one has added the line:
 112 .Bd -literal
 113 503     STD     BSD     { int mycall(int x, int y); }
 114 .Ed
 115 .Pp
 116 to 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
 121 It is customary to extract system call arguments with the
 122 .Fn SCARG uap member
 123 macro, which is defined in
 124 .Pa sys/sys/sysent.h
 125 file.
 126 Last, in order to return a value to userland, the
 127 .Fa uap->sysmsg_result
 128 variable and friends of it are used, as defined in
 129 .Pa sys/sys/sysmsg.h .
 130 .Sh IMPLEMENTATION NOTES
 131 In the kernel, a syscall is implemented by a
 132 .Fn sys_syscallname
 133 function.
 134 In userspace, the function that executes a syscall is automatically generated
 135 using the description in
 136 .Pa syscalls.master .
 137 The symbols in the
 138 .Lb libc
 139 are assembly wrappers generated in
 140 .Pa lib/libc/${MACHINE_ARCH} Pq e.g.\& x86_64 ,
 141 again using the description in
 142 .Pa syscalls.master .
 143 These wrappers use macros provided by the platform-dependent
 144 .In SYS.h
 145 header file which take care of putting the syscall arguments into registers
 146 (per the ABI specification) and inserting a
 147 .Li syscall
 148 instruction (on x86_64).
 149 .Sh FILES
 150 .Bl -tag -width sys/kern/syscalls.master -compact
 151 .It Pa sys/kern/makesyscalls.sh
 152 a
 153 .Xr sh 1
 154 script for generating C files out of the syscall master file;
 155 .It Pa sys/kern/syscalls.conf
 156 a configuration file for the shell script above;
 157 .It Pa sys/kern/syscalls.master
 158 master files describing names and numbers for the system calls;
 159 .It Pa sys/kern/syscalls.c
 160 system call names lists;
 161 .It Pa sys/kern/init_sysent.c
 162 system call switch tables;
 163 .It Pa sys/sys/sysproto.h
 164 system call argument lists;
 165 .It Pa sys/sys/syscall.h
 166 system 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
 175 The
 176 .Nm
 177 section manual page appeared in
 178 .Dx 2.3 .