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