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 $Mdocdate: May 31 2007 $ 27.Dt SYSCALL 9 28.Os 29.Sh NAME 30.Nm syscall 31.Nd "system calls overview" 32.Sh DESCRIPTION 33System calls in the kernel are implemented through a set of 34switch tables for each emulation type. 35Each table is generated from the 36.Dq master 37file by 38.Pa sys/kern/makesyscalls.sh 39through the appropriate rules in the 40.Pa Makefile . 41.Pp 42The 43.Dq master 44file is a text file consisting of a list of lines for each 45system call. 46Lines may be split by the means of back slashing the end of the line. 47Each line is a set of fields separated by whitespace: 48.Pp 49.D1 Cd number type ... 50.Pp 51Where: 52.Bl -tag -width number -compact 53.It number 54is the system call number; 55.It type 56is one of: 57.Bl -tag -width COMPAT_XXX -compact 58.It STD 59always included; 60.It OBSOL 61obsolete, not included in the system; 62.It UNIMPL 63unimplemented, not included in the system; 64.It NODEF 65included, but don't define the syscall number; 66.It NOARGS 67included, but don't define the syscall args structure; 68.It INDIR 69included, but don't define the syscall args structure, 70and allow it to be "really" varargs; 71.It COMPAT_XX 72a compatibility system call, only included if the corresponding 73option is configured for the kernel (see 74.Xr options 4 ) . 75.El 76.El 77.Pp 78The rest of the line for the STD, NODEF, NOARGS, and COMPAT_XX 79types is: 80.Pp 81.D1 Cd { pseudo-proto } [alias] 82.Pp 83.Nm pseudo-proto 84is a C-like prototype used to generate the system call argument list, 85and alias is an optional name alias for the call. 86The function in the prototype has to be defined somewhere in 87the kernel sources as it will be used as an entry point for 88the corresponding system call. 89.Pp 90For other types the rest of the line is a comment. 91.Pp 92To generate the header and code files from the 93.Dq master 94file a 95.Xr make 1 96command has to be run from the directory containing the 97.Dq master 98file. 99.Ss Usage 100Entry from the user space for the system call is machine dependent. 101Typical code to invoke a system call from the machine dependent 102sources might look like this: 103.Bd -literal -offset indent 104 105 const struct sysent *callp; 106 register_t code, args[8], rval[2]; 107 struct proc *p = curproc; 108 int code, nsys; 109 110\&... 111 112/* ``code'' is the system call number passed from the user space */ 113 114\&... 115 116if (code < 0 || code >= nsys) 117 callp += p->p_emul->e_nosys; /* illegal */ 118else 119 callp += code; 120 121/* copyin the arguments from the user space */ 122\&... 123 124#ifdef SYSCALL_DEBUG 125 scdebug_call(p, code, args); 126#endif 127#ifdef KTRACE 128 if (KTRPOINT(p, KTR_SYSCALL)) 129 ktrsyscall(p, code, argsize, args); 130#endif 131 rval[0] = 0; 132#if NSYSTRACE > 0 133 if (ISSET(p->p_flag, P_SYSTRACE)) 134 error = systrace_redirect(code, p, args, rval); 135 else 136#endif 137 error = (*callp->sy_call)(p, args, rval); 138 switch (error) { 139 case 0: 140 /* normal return */ 141 \&... 142 break; 143 case ERESTART: 144 /* 145 * adjust PC to point before the system call 146 * in the user space in order for the return 147 * back there we reenter the kernel to repeat 148 * the same system call 149 */ 150 \&... 151 break; 152 case EJUSTRETURN: 153 /* just return */ 154 break; 155 default: 156 /* 157 * an error returned: 158 * call an optional emulation errno mapping 159 * routine and return back to the user. 160 */ 161 if (p->p_emul->e_errno) 162 error = p->p_emul->e_errno[error]; 163 \&... 164 break; 165 } 166#ifdef SYSCALL_DEBUG 167 scdebug_ret(p, code, orig_error, rval); 168#endif 169 userret(p, frame.tf_eip, sticks); 170#ifdef KTRACE 171 if (KTRPOINT(p, KTR_SYSRET)) 172 ktrsysret(p, code, orig_error, rval[0]); 173#endif 174 175.Ed 176.Pp 177The 178.Dq SYSCALL_DEBUG 179parts of the code are explained in the section 180.Sx Debugging 181later in the document. 182For the 183.Dq KTRACE 184portions of the code refer to the 185.Xr ktrace 9 186document for further explanations. 187.Dq NSYSTRACE 188is a system call tracing facility and is explained in the 189.Xr systrace 9 190and 191.Xr systrace 4 192documents. 193.Ss Debugging 194For debugging purposes the line 195.Pp 196.D1 Cd option SYSCALL_DEBUG 197.Pp 198should be included in the kernel configuration file (see 199.Xr options 4 ) . 200This allows tracing for calls, returns, and arguments for both 201implemented and non-implemented system calls. 202A global integer variable 203.Dr scdebug 204contains a mask for the desired logging events: 205.Pp 206.Bl -tag -width SCDEBUG_SHOWARGS__ -compact 207.It SCDEBUG_CALLS 208(0x0001) show calls; 209.It SCDEBUG_RETURNS 210(0x0002) show returns; 211.It SCDEBUG_ALL 212(0x0004) show even syscalls that are implemented; 213.It SCDEBUG_SHOWARGS 214(0x0008) show arguments to calls. 215.El 216.Pp 217Use 218.Xr ddb 4 219to set the 220.Dq scdebug 221to a value desired. 222.Sh CODE REFERENCES 223.Bl -tag -width sys/kern/syscalls.master -compact 224.It Pa sys/kern/makesyscalls.sh 225a 226.Xr sh 1 227script for generating C files out of the syscall master file; 228.It Pa sys/{kern,compat/*}/syscalls.conf 229a configuration file for the shell script above; 230.It Pa sys/{kern,compat/*}/syscalls.master 231master files describing names and numbers for the system calls; 232.It Pa sys/{kern/,compat/*/*_}syscalls.c 233system call names lists; 234.It Pa sys/{kern/init,compat/*/*}_sysent.c 235system call switch tables; 236.It Pa sys/{sys/,compat/*/*_}syscallargs.h 237system call argument lists; 238.It Pa sys/{sys/,compat/*/*_}syscall.h 239system call numbers. 240.El 241.Sh SEE ALSO 242.Xr ktrace 2 , 243.Xr syscall 2 , 244.Xr systrace 4 , 245.Xr ktrace 9 , 246.Xr sysctl_int 9 , 247.Xr systrace 9 248.Sh HISTORY 249The 250.Nm 251section manual page appeared in 252.Ox 3.4 . 253