From: Stathis Kamperis Date: Sun, 17 May 2009 13:28:05 +0000 (+0300) Subject: Add syscall.9 adapted from OpenBSD. X-Git-Tag: v2.3.2~235^2~27 X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/commitdiff_plain/ccab178b0e0c5b1cedeec0e6e0a8c7517df51809 Add syscall.9 adapted from OpenBSD. Reviewed-by: swildner@ --- diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index c99ed6b084..492491ff19 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -129,6 +129,7 @@ MAN= accept_filter.9 \ style.9 \ suser.9 \ SYSCALL_MODULE.9 \ + syscall.9 \ sysctl.9 \ sysctl_add_oid.9 \ sysctl_ctx_init.9 \ diff --git a/share/man/man9/syscall.9 b/share/man/man9/syscall.9 new file mode 100644 index 0000000000..fe9cc2ab47 --- /dev/null +++ b/share/man/man9/syscall.9 @@ -0,0 +1,161 @@ +.\" $OpenBSD: syscall.9,v 1.7 2007/05/31 19:20:01 jmc Exp $ +.\" +.\" Copyright (c) 2003 Michael Shalayeff +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF MIND, USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 25, 2009 +.Dt SYSCALL 9 +.Os +.Sh NAME +.Nm syscall +.Nd "system calls overview" +.Sh DESCRIPTION +A system call is an explicit request to the kernel made via a software +interrupt by some program. +For example, +.Fn open +is a system call that is used when access to a file stored in filesystem +is needed. +In this sense, system calls provide the interface between a process and the +operating system. +.Pp +The kernel implements system calls through a set of switch tables +for each emulation type. +The list of currently supported system calls along with their codes resides in +.Pa sys/sys/syscall.h . +This file, and a couple others which will be examined later, are +automatically generated and should not be edited manually. +.Pp +The first step in adding a new system call is to edit the +.Pa sys/kern/syscall.masters +file. +The +.Dq master +file is a text file consisting of a list of lines for each +system call. +Lines may be split by the means of back slashing the end of the line. +Each line is a set of fields separated by whitespace: +.Pp +.D1 Cd number type namespace ... +.Pp +Where: +.Bl -tag -width namespace -compact +.It number +is the system call number; +.It namespace +is one of POSIX, BSD, NOHIDE; +.It type +is one of: +.Bl -tag -width NOPROTO -compact +.It STD +standard system call with full prototype and implementation; +.It OBSOL +obsolete, not included in the system; +.It UNIMPL +unimplemented, not included in the system, placeholder only; +.It NODEF +included, but don't define the syscall number; +.It NOARGS +included, but don't define the syscall args structure; +.It NOPROTO +implemented elsewhere; +.It COMPAT +a compatibility system call, only included if the corresponding +option is configured for the kernel. +.El +.El +.Pp +The rest of the line for the STD, NODEF, NOARGS, and COMPAT +types is: +.Pp +.D1 Cd { pseudo-proto } [alias] +.Pp +.Nm pseudo-proto +is a C-like prototype used to generate the system call argument list, +and alias is an optional name alias for the call. +The function in the prototype has to be defined somewhere in +the kernel sources as it will be used as an entry point for +the corresponding system call. +.Pp +For other types the rest of the line is a comment. +.Pp +To generate the header and code files from the +.Dq master +file, +.Li make sysent +has to be run from the directory containing the +.Dq master +file. +Please mind that the string +.Li sys_ +is prepended to all system call names, but not to the structures +holding the arguments. +So, if one has added the line: +.Bd -literal +503 STD BSD { int mycall(int x, int y); } +.Ed +.Pp +to the system call master file, the generated prototype would be: +.Bd -literal +int sys_mycall(struct mycall_args *uap); +.Ed +.Pp +It is customary to extract system call arguments with the +.Dv SCARG(uap, member) +macro, which is defined in +.Pa sys/sys/sysent.h +file. +Last, in order to return a value to userland, the +.Li uap->sysmsg_result +variable and friends of it are used, as defined in +.Pa sys/sys/sysmsg.h . +.Sh FILES +.Bl -tag -width sys/kern/syscalls.master -compact +.It Pa sys/kern/makesyscalls.sh +a +.Xr sh 1 +script for generating C files out of the syscall master file; +.It Pa sys/kern/syscalls.conf +a configuration file for the shell script above; +.It Pa sys/kern/syscalls.master +master files describing names and numbers for the system calls; +.It Pa sys/kern/syscalls.c +system call names lists; +.It Pa sys/kern/init_sysent.c +system call switch tables; +.It Pa sys/sys/sysproto.h +system call argument lists; +.It Pa sys/sys/syscall.h +system call numbers. +.It Pa sys/emulation/linux/i386 +Linux emulation system calls. +.El +.Sh SEE ALSO +.Xr ktrace 2 , +.Xr syscall 2 , +.Xr SYSCALL_MODULE 9 +.Sh HISTORY +The +.Nm +section manual page appeared in +.Dx 2.3 .