@@ -1,4 +1,4 @@
-.\"	$NetBSD: syscall.2,v 1.17 2007/11/23 20:29:40 dsl Exp $
+.\"	$NetBSD: syscall.2,v 1.18 2009/08/07 19:34:46 dsl Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"     @(#)syscall.2	8.1 (Berkeley) 6/16/93
 .\"
-.Dd November 23, 2006
+.Dd August 7, 2009
 .Dt SYSCALL 2
 .Os
 .Sh NAME
@@ -57,8 +57,10 @@
 .Nm __syscall
 form should be used when one or more of the parameters is a
 64-bit argument to ensure that argument alignment is correct.
+.Pp
 This system call is useful for testing new system calls that
 do not have entries in the C library.
+It should not be used in normal applications.
 .Sh RETURN VALUES
 The return values are defined by the system call being invoked.
 In general, a 0 return value indicates success.
@@ -82,6 +84,9 @@
 For instance sparc returns 32 bit values in %o0 and 64 bit values in %o0:%o1
 (with %o0 containing the most significant part) so a 32 bit right shift
 of the result is needed to get a correct 32 bit result.
+.Pp
+Many architectures mask off the unwanted high bits of the syscall number,
+rather than returning an error.
 .Pp
 Due to ABI implementation differences in passing struct or union
 type arguments to system calls between different processors, all