Add text to the description saying that normal applications should not

use syscall().
Add text to bugs saying that high bits of the syscall number may be masked.
Fixes bug PR/11088

lib/libc/sys/syscall.2

@@ -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 @@ The
 .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.
@@ -83,6 +85,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
 system calls pass instead pointers to such structs or unions, even