Add syscall.9 adapted from OpenBSD.
authorStathis Kamperis <beket@dragonflybsd.org>
Sun, 17 May 2009 13:28:05 +0000 (16:28 +0300)
committerStathis Kamperis <beket@dragonflybsd.org>
Mon, 25 May 2009 09:56:49 +0000 (12:56 +0300)
Reviewed-by: swildner@
share/man/man9/Makefile
share/man/man9/syscall.9 [new file with mode: 0644]

index c99ed6b..492491f 100644 (file)
@@ -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 (file)
index 0000000..fe9cc2a
--- /dev/null
@@ -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 .