| @@ -1,94 +1,99 @@ | | | @@ -1,94 +1,99 @@ |
1 | .\" $NetBSD: syscall.2,v 1.17 2007/11/23 20:29:40 dsl Exp $ | | 1 | .\" $NetBSD: syscall.2,v 1.18 2009/08/07 19:34:46 dsl Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c) 1980, 1991, 1993 | | 3 | .\" Copyright (c) 1980, 1991, 1993 |
4 | .\" The Regents of the University of California. All rights reserved. | | 4 | .\" The Regents of the University of California. All rights reserved. |
5 | .\" | | 5 | .\" |
6 | .\" Redistribution and use in source and binary forms, with or without | | 6 | .\" Redistribution and use in source and binary forms, with or without |
7 | .\" modification, are permitted provided that the following conditions | | 7 | .\" modification, are permitted provided that the following conditions |
8 | .\" are met: | | 8 | .\" are met: |
9 | .\" 1. Redistributions of source code must retain the above copyright | | 9 | .\" 1. Redistributions of source code must retain the above copyright |
10 | .\" notice, this list of conditions and the following disclaimer. | | 10 | .\" notice, this list of conditions and the following disclaimer. |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 11 | .\" 2. Redistributions in binary form must reproduce the above copyright |
12 | .\" notice, this list of conditions and the following disclaimer in the | | 12 | .\" notice, this list of conditions and the following disclaimer in the |
13 | .\" documentation and/or other materials provided with the distribution. | | 13 | .\" documentation and/or other materials provided with the distribution. |
14 | .\" 3. Neither the name of the University nor the names of its contributors | | 14 | .\" 3. Neither the name of the University nor the names of its contributors |
15 | .\" may be used to endorse or promote products derived from this software | | 15 | .\" may be used to endorse or promote products derived from this software |
16 | .\" without specific prior written permission. | | 16 | .\" without specific prior written permission. |
17 | .\" | | 17 | .\" |
18 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | | 18 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
19 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | | 19 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
20 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 20 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
21 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | | 21 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
22 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 22 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
23 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 23 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
24 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 24 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
25 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | | 25 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
26 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | | 26 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
27 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | | 27 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
28 | .\" SUCH DAMAGE. | | 28 | .\" SUCH DAMAGE. |
29 | .\" | | 29 | .\" |
30 | .\" @(#)syscall.2 8.1 (Berkeley) 6/16/93 | | 30 | .\" @(#)syscall.2 8.1 (Berkeley) 6/16/93 |
31 | .\" | | 31 | .\" |
32 | .Dd November 23, 2006 | | 32 | .Dd August 7, 2009 |
33 | .Dt SYSCALL 2 | | 33 | .Dt SYSCALL 2 |
34 | .Os | | 34 | .Os |
35 | .Sh NAME | | 35 | .Sh NAME |
36 | .Nm syscall , | | 36 | .Nm syscall , |
37 | .Nm __syscall | | 37 | .Nm __syscall |
38 | .Nd indirect system call | | 38 | .Nd indirect system call |
39 | .Sh LIBRARY | | 39 | .Sh LIBRARY |
40 | .Lb libc | | 40 | .Lb libc |
41 | .Sh SYNOPSIS | | 41 | .Sh SYNOPSIS |
42 | .In sys/syscall.h | | 42 | .In sys/syscall.h |
43 | .In unistd.h | | 43 | .In unistd.h |
44 | .Ft int | | 44 | .Ft int |
45 | .Fn syscall "int number" "..." | | 45 | .Fn syscall "int number" "..." |
46 | .Ft quad_t | | 46 | .Ft quad_t |
47 | .Fn __syscall "quad_t number" "..." | | 47 | .Fn __syscall "quad_t number" "..." |
48 | .Sh DESCRIPTION | | 48 | .Sh DESCRIPTION |
49 | .Fn syscall | | 49 | .Fn syscall |
50 | performs the system call whose assembly language | | 50 | performs the system call whose assembly language |
51 | interface has the specified | | 51 | interface has the specified |
52 | .Fa number | | 52 | .Fa number |
53 | with the specified arguments. | | 53 | with the specified arguments. |
54 | Symbolic constants for system calls can be found in the header file | | 54 | Symbolic constants for system calls can be found in the header file |
55 | .Ao Pa sys/syscall.h Ac . | | 55 | .Ao Pa sys/syscall.h Ac . |
56 | The | | 56 | The |
57 | .Nm __syscall | | 57 | .Nm __syscall |
58 | form should be used when one or more of the parameters is a | | 58 | form should be used when one or more of the parameters is a |
59 | 64-bit argument to ensure that argument alignment is correct. | | 59 | 64-bit argument to ensure that argument alignment is correct. |
| | | 60 | .Pp |
60 | This system call is useful for testing new system calls that | | 61 | This system call is useful for testing new system calls that |
61 | do not have entries in the C library. | | 62 | do not have entries in the C library. |
| | | 63 | It should not be used in normal applications. |
62 | .Sh RETURN VALUES | | 64 | .Sh RETURN VALUES |
63 | The return values are defined by the system call being invoked. | | 65 | The return values are defined by the system call being invoked. |
64 | In general, a 0 return value indicates success. | | 66 | In general, a 0 return value indicates success. |
65 | A \-1 return value indicates an error, | | 67 | A \-1 return value indicates an error, |
66 | and an error code is stored in | | 68 | and an error code is stored in |
67 | .Va errno . | | 69 | .Va errno . |
68 | .Sh HISTORY | | 70 | .Sh HISTORY |
69 | The | | 71 | The |
70 | .Fn syscall | | 72 | .Fn syscall |
71 | function call appeared in | | 73 | function call appeared in |
72 | .Bx 4.0 . | | 74 | .Bx 4.0 . |
73 | .Sh BUGS | | 75 | .Sh BUGS |
74 | There is no way to simulate system calls that have multiple return values | | 76 | There is no way to simulate system calls that have multiple return values |
75 | such as | | 77 | such as |
76 | .Xr pipe 2 . | | 78 | .Xr pipe 2 . |
77 | .Pp | | 79 | .Pp |
78 | Since architectures return 32 bit and 64 bit results in different registers, | | 80 | Since architectures return 32 bit and 64 bit results in different registers, |
79 | it may be impossible to portably convert the result of | | 81 | it may be impossible to portably convert the result of |
80 | .Fn __syscall | | 82 | .Fn __syscall |
81 | to a 32bit value. | | 83 | to a 32bit value. |
82 | For instance sparc returns 32 bit values in %o0 and 64 bit values in %o0:%o1 | | 84 | For instance sparc returns 32 bit values in %o0 and 64 bit values in %o0:%o1 |
83 | (with %o0 containing the most significant part) so a 32 bit right shift | | 85 | (with %o0 containing the most significant part) so a 32 bit right shift |
84 | of the result is needed to get a correct 32 bit result. | | 86 | of the result is needed to get a correct 32 bit result. |
85 | .Pp | | 87 | .Pp |
| | | 88 | Many architectures mask off the unwanted high bits of the syscall number, |
| | | 89 | rather than returning an error. |
| | | 90 | .Pp |
86 | Due to ABI implementation differences in passing struct or union | | 91 | Due to ABI implementation differences in passing struct or union |
87 | type arguments to system calls between different processors, all | | 92 | type arguments to system calls between different processors, all |
88 | system calls pass instead pointers to such structs or unions, even | | 93 | system calls pass instead pointers to such structs or unions, even |
89 | when the documentation of the system call mentions otherwise. | | 94 | when the documentation of the system call mentions otherwise. |
90 | The conversion between passing structs and unions is handled normally | | 95 | The conversion between passing structs and unions is handled normally |
91 | via userland stubs. | | 96 | via userland stubs. |
92 | The correct arguments for the kernel entry | | 97 | The correct arguments for the kernel entry |
93 | points for each system call can be found in the header file | | 98 | points for each system call can be found in the header file |
94 | .Ao Pa sys/syscallargs.h Ac | | 99 | .Ao Pa sys/syscallargs.h Ac |