]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1980, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
a9cd9cb7 | 4 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. All advertising materials mentioning features or use of this software | |
14 | .\" must display the following acknowledgement: | |
15 | .\" This product includes software developed by the University of | |
16 | .\" California, Berkeley and its contributors. | |
17 | .\" 4. Neither the name of the University nor the names of its contributors | |
18 | .\" may be used to endorse or promote products derived from this software | |
19 | .\" without specific prior written permission. | |
20 | .\" | |
21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
8c9302dc | 32 | .\" %%%LICENSE_END |
fea681da MK |
33 | .\" |
34 | .\" @(#)syscall.2 8.1 (Berkeley) 6/16/93 | |
35 | .\" | |
36 | .\" | |
37 | .\" 2002-03-20 Christoph Hellwig <hch@infradead.org> | |
38 | .\" - adopted for Linux | |
1a145eee KC |
39 | .\" 2015-01-17, Kees Cook <keescook@chromium.org> |
40 | .\" Added mips and arm64. | |
fea681da | 41 | .\" |
97986708 | 42 | .TH SYSCALL 2 2016-03-15 "Linux" "Linux Programmer's Manual" |
c046a641 MK |
43 | .SH NAME |
44 | syscall \- indirect system call | |
45 | .SH SYNOPSIS | |
46 | .nf | |
b80f966b | 47 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
c046a641 | 48 | .B #include <unistd.h> |
cc4615cc | 49 | .BR "#include <sys/syscall.h> " "/* For SYS_xxx definitions */" |
c046a641 | 50 | |
24313b88 | 51 | .BI "long syscall(long " number ", ...);" |
c046a641 MK |
52 | .fi |
53 | .SH DESCRIPTION | |
54 | .BR syscall () | |
498a96a2 MK |
55 | is a small library function that invokes |
56 | the system call whose assembly language | |
fea681da | 57 | interface has the specified |
c046a641 | 58 | .I number |
fea681da | 59 | with the specified arguments. |
498a96a2 MK |
60 | Employing |
61 | .BR syscall () | |
62 | is useful, for example, | |
63 | when invoking a system call that has no wrapper function in the C library. | |
64 | ||
65 | .BR syscall () | |
66 | saves CPU registers before making the system call, | |
67 | restores the registers upon return from the system call, | |
68 | and stores any error code returned by the system call in | |
69 | .BR errno (3) | |
70 | if an error occurs. | |
71 | ||
72 | Symbolic constants for system call numbers can be found in the header file | |
c046a641 MK |
73 | .IR <sys/syscall.h> . |
74 | .SH RETURN VALUE | |
fea681da MK |
75 | The return value is defined by the system call being invoked. |
76 | In general, a 0 return value indicates success. | |
8729177b | 77 | A \-1 return value indicates an error, |
fea681da | 78 | and an error code is stored in |
c046a641 MK |
79 | .IR errno . |
80 | .SH NOTES | |
81 | .BR syscall () | |
82 | first appeared in | |
83 | 4BSD. | |
bed6b26e | 84 | .SS Architecture-specific requirements |
95253016 MK |
85 | Each architecture ABI has its own requirements on how |
86 | system call arguments are passed to the kernel. | |
87 | For system calls that have a glibc wrapper (e.g., most system calls), | |
bed6b26e | 88 | glibc handles the details of copying arguments to the right registers |
95253016 | 89 | in a manner suitable for the architecture. |
638fd4bf CH |
90 | However, when using |
91 | .BR syscall () | |
92 | to make a system call, | |
bed6b26e MK |
93 | the caller might need to handle architecture-dependent details; |
94 | this requirement is most commonly encountered on certain 32-bit architectures. | |
638fd4bf | 95 | |
bed6b26e MK |
96 | For example, on the ARM architecture Embedded ABI (EABI), a |
97 | 64-bit value (e.g., | |
98 | .IR "long long" ) | |
99 | must be aligned to an even register pair. | |
100 | Thus, using | |
101 | .BR syscall () | |
102 | instead of the wrapper provided by glibc, | |
103 | the | |
638fd4bf | 104 | .BR readahead () |
9e5c5e5f | 105 | system call would be invoked as follows on the ARM architecture with the EABI: |
638fd4bf | 106 | |
95253016 MK |
107 | .in +4n |
108 | .nf | |
bed6b26e MK |
109 | syscall(SYS_readahead, fd, 0, |
110 | (unsigned int) (offset >> 32), | |
111 | (unsigned int) (offset & 0xFFFFFFFF), | |
112 | count); | |
95253016 MK |
113 | .fi |
114 | .in | |
115 | .PP | |
bed6b26e MK |
116 | Since the offset argument is 64 bits, and the first argument |
117 | .RI ( fd ) | |
118 | is passed in | |
119 | .IR r0 , | |
ca972ff9 MK |
120 | the caller must manually split and align the 64-bit value |
121 | so that it is passed in the | |
bed6b26e MK |
122 | .IR r2 / r3 |
123 | register pair. | |
124 | That means inserting a dummy value into | |
125 | .I r1 | |
126 | (the second argument of 0). | |
127 | ||
128 | Similar issues can occur on MIPS with the O32 ABI, | |
129 | on PowerPC with the 32-bit ABI, and on Xtensa. | |
130 | .\" Mike Frysinger: this issue ends up forcing MIPS | |
131 | .\" O32 to take 7 arguments to syscall() | |
132 | ||
9e5c5e5f | 133 | The affected system calls are |
bed6b26e MK |
134 | .BR fadvise64_64 (2), |
135 | .BR ftruncate64 (2), | |
136 | .BR posix_fadvise (2), | |
137 | .BR pread64 (2), | |
138 | .BR pwrite64 (2), | |
139 | .BR readahead (2), | |
140 | .BR sync_file_range (2), | |
9e5c5e5f MK |
141 | and |
142 | .BR truncate64 (2). | |
08c9b3b9 MK |
143 | .SS Architecture calling conventions |
144 | Every architecture has its own way of invoking and passing arguments to the | |
145 | kernel. | |
146 | The details for various architectures are listed in the two tables below. | |
147 | ||
ddbe84e6 | 148 | The first table lists the instruction used to transition to kernel mode |
08c9b3b9 | 149 | (which might not be the fastest or best way to transition to the kernel, |
951ae9c0 MF |
150 | so you might have to refer to |
151 | .BR vdso (7)), | |
08c9b3b9 | 152 | the register used to indicate the system call number, |
8585e837 MF |
153 | the register used to return the system call result, |
154 | and the register used to signal an error. | |
08c9b3b9 MK |
155 | .if t \{\ |
156 | .ft CW | |
157 | \} | |
158 | .TS | |
9f9a9b76 | 159 | l2 l2 l2 l2 l2 l. |
8585e837 | 160 | arch/ABI instruction syscall # retval error Notes |
08c9b3b9 | 161 | _ |
9f9a9b76 | 162 | alpha callsys v0 a0 a3 [1] |
8585e837 | 163 | arc trap0 r8 r0 - |
9f9a9b76 | 164 | arm/OABI swi NR - a1 - [2] |
8585e837 MF |
165 | arm/EABI swi 0x0 r7 r0 - |
166 | arm64 svc #0 x8 x0 - | |
167 | blackfin excpt 0x0 P0 R0 - | |
168 | i386 int $0x80 eax eax - | |
9f9a9b76 | 169 | ia64 break 0x100000 r15 r8 r10 [1] |
8585e837 MF |
170 | m68k trap #0 d0 d0 - |
171 | microblaze brki r14,8 r12 r3 - | |
9f9a9b76 | 172 | mips syscall v0 v0 a3 [1] |
8585e837 MF |
173 | nios2 trap r2 r2 r7 |
174 | parisc ble 0x100(%sr2, %r0) r20 r28 - | |
9f9a9b76 MK |
175 | powerpc sc r0 r3 r0 [1] |
176 | s390 svc 0 r1 r2 - [3] | |
177 | s390x svc 0 r1 r2 - [3] | |
178 | superh trap #0x17 r3 r0 - [4] | |
179 | sparc/32 t 0x10 g1 o0 psr/csr [1] | |
180 | sparc/64 t 0x6d g1 o0 psr/csr [1] | |
181 | tile swint1 R10 R00 R01 [1] | |
182 | x86_64 syscall rax rax - [5] | |
183 | x32 syscall rax rax - [5] | |
8585e837 | 184 | xtensa syscall a2 a2 - |
08c9b3b9 | 185 | .TE |
19a225b0 | 186 | .PP |
9f9a9b76 MK |
187 | Notes: |
188 | .RS 4 | |
189 | .IP [1] 4 | |
8585e837 | 190 | On a few architectures, |
1078a699 MK |
191 | a register is used as a boolean |
192 | (0 indicating no error, and \-1 indicating an error) to signal that the | |
8585e837 MF |
193 | system call failed. |
194 | The actual error value is still contained in the return register. | |
1078a699 MK |
195 | On sparc, the carry bit |
196 | .RI ( csr ) | |
197 | in the processor status register | |
3438c516 | 198 | .RI ( psr ) |
1078a699 | 199 | is used instead of a full register. |
9f9a9b76 | 200 | .IP [2] |
1078a699 MK |
201 | .I NR |
202 | is the system call number. | |
9f9a9b76 | 203 | .IP [3] |
1078a699 MK |
204 | For s390 and s390x, |
205 | .I NR | |
206 | (the system call number) may be passed directly with | |
207 | .I "svc\ NR" | |
208 | if it is less than 256. | |
9f9a9b76 | 209 | .IP [4] |
1078a699 MK |
210 | On SuperH, the trap number controls the maximum number of arguments passed. |
211 | A | |
212 | .IR "trap\ #0x10" | |
213 | can be used with only 0-argument system calls, a | |
214 | .IR "trap\ #0x11" | |
215 | can be used with 0- or 1-argument system calls, | |
216 | and so on up to | |
217 | .IR "trap #0x17" | |
218 | for 7-argument system calls. | |
9f9a9b76 | 219 | .IP [5] |
9ccd62fc | 220 | The x32 ABI uses the same instruction as the x86_64 ABI and is used on |
1e941e8c MK |
221 | the same processors. |
222 | To differentiate between them, the bit mask | |
9ccd62fc | 223 | .I __X32_SYSCALL_BIT |
1e941e8c MK |
224 | is bitwise-ORed into the system call number for system calls |
225 | under the x32 ABI. | |
1078a699 MK |
226 | Both system call tables are available though, |
227 | so setting the bit is not a hard requirement. | |
9f9a9b76 | 228 | .RE |
08c9b3b9 MK |
229 | .if t \{\ |
230 | .in | |
231 | .ft P | |
232 | \} | |
233 | .PP | |
234 | The second table shows the registers used to pass the system call arguments. | |
235 | .if t \{\ | |
236 | .ft CW | |
237 | \} | |
238 | .TS | |
661824b4 MK |
239 | l l2 l2 l2 l2 l2 l2 l2 l. |
240 | arch/ABI arg1 arg2 arg3 arg4 arg5 arg6 arg7 Notes | |
08c9b3b9 | 241 | _ |
8585e837 MF |
242 | alpha a0 a1 a2 a3 a4 a5 - |
243 | arc r0 r1 r2 r3 r4 r5 - | |
661824b4 MK |
244 | arm/OABI a1 a2 a3 a4 v1 v2 v3 |
245 | arm/EABI r0 r1 r2 r3 r4 r5 r6 | |
246 | arm64 x0 x1 x2 x3 x4 x5 - | |
247 | blackfin R0 R1 R2 R3 R4 R5 - | |
248 | i386 ebx ecx edx esi edi ebp - | |
249 | ia64 out0 out1 out2 out3 out4 out5 - | |
8585e837 MF |
250 | m68k d1 d2 d3 d4 d5 a0 - |
251 | microblaze r5 r6 r7 r8 r9 r10 - | |
9f9a9b76 | 252 | mips/o32 a0 a1 a2 a3 - - - [1] |
661824b4 | 253 | mips/n32,64 a0 a1 a2 a3 a4 a5 - |
8585e837 | 254 | nios2 r4 r5 r6 r7 r8 r9 - |
661824b4 | 255 | parisc r26 r25 r24 r23 r22 r21 - |
8585e837 | 256 | powerpc r3 r4 r5 r6 r7 r8 r9 |
661824b4 MK |
257 | s390 r2 r3 r4 r5 r6 r7 - |
258 | s390x r2 r3 r4 r5 r6 r7 - | |
8585e837 | 259 | superh r4 r5 r6 r7 r0 r1 r2 |
661824b4 MK |
260 | sparc/32 o0 o1 o2 o3 o4 o5 - |
261 | sparc/64 o0 o1 o2 o3 o4 o5 - | |
8585e837 | 262 | tile R00 R01 R02 R03 R04 R05 - |
661824b4 MK |
263 | x86_64 rdi rsi rdx r10 r8 r9 - |
264 | x32 rdi rsi rdx r10 r8 r9 - | |
8585e837 | 265 | xtensa a6 a3 a4 a5 a8 a9 - |
08c9b3b9 | 266 | .TE |
1a145eee | 267 | .PP |
9f9a9b76 MK |
268 | Notes: |
269 | .RS 4 | |
270 | .IP [1] 4 | |
70fdf8d0 MK |
271 | The mips/o32 system call convention passes |
272 | arguments 5 through 8 on the user stack. | |
9f9a9b76 | 273 | .RE |
08c9b3b9 MK |
274 | .if t \{\ |
275 | .in | |
276 | .ft P | |
277 | \} | |
278 | .PP | |
279 | Note that these tables don't cover the entire calling convention\(emsome | |
280 | architectures may indiscriminately clobber other registers not listed here. | |
c046a641 | 281 | .SH EXAMPLE |
c046a641 MK |
282 | .nf |
283 | #define _GNU_SOURCE | |
284 | #include <unistd.h> | |
285 | #include <sys/syscall.h> | |
286 | #include <sys/types.h> | |
415f7e63 | 287 | #include <signal.h> |
c046a641 MK |
288 | |
289 | int | |
290 | main(int argc, char *argv[]) | |
291 | { | |
292 | pid_t tid; | |
863b571e | 293 | |
fa66abf8 | 294 | tid = syscall(SYS_gettid); |
415f7e63 | 295 | tid = syscall(SYS_tgkill, getpid(), tid, SIGHUP); |
c046a641 MK |
296 | } |
297 | .fi | |
c58418c9 | 298 | .SH SEE ALSO |
0c2b92ba | 299 | .BR _syscall (2), |
f0c34053 | 300 | .BR intro (2), |
951ae9c0 | 301 | .BR syscalls (2), |
4e0b8e82 | 302 | .BR errno (3), |
951ae9c0 | 303 | .BR vdso (7) |