1 .\" Copyright (c) 1980, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
34 .\" @(#)syscall.2 8.1 (Berkeley) 6/16/93
37 .\" 2002-03-20 Christoph Hellwig <hch@infradead.org>
38 .\" - adopted for Linux
39 .\" 2015-01-17, Kees Cook <keescook@chromium.org>
40 .\" Added mips and arm64.
42 .TH SYSCALL 2 2020-02-09 "Linux" "Linux Programmer's Manual"
44 syscall \- indirect system call
47 .B #include <unistd.h>
48 .BR "#include <sys/syscall.h> " "/* For SYS_xxx definitions */"
50 .BI "long syscall(long " number ", ...);"
54 Feature Test Macro Requirements for glibc (see
55 .BR feature_test_macros (7)):
66 _BSD_SOURCE || _SVID_SOURCE
72 is a small library function that invokes
73 the system call whose assembly language
74 interface has the specified
76 with the specified arguments.
79 is useful, for example,
80 when invoking a system call that has no wrapper function in the C library.
83 saves CPU registers before making the system call,
84 restores the registers upon return from the system call,
85 and stores any error code returned by the system call in
89 Symbolic constants for system call numbers can be found in the header file
92 The return value is defined by the system call being invoked.
93 In general, a 0 return value indicates success.
94 A \-1 return value indicates an error,
95 and an error code is stored in
101 .SS Architecture-specific requirements
102 Each architecture ABI has its own requirements on how
103 system call arguments are passed to the kernel.
104 For system calls that have a glibc wrapper (e.g., most system calls),
105 glibc handles the details of copying arguments to the right registers
106 in a manner suitable for the architecture.
109 to make a system call,
110 the caller might need to handle architecture-dependent details;
111 this requirement is most commonly encountered on certain 32-bit architectures.
113 For example, on the ARM architecture Embedded ABI (EABI), a
116 must be aligned to an even register pair.
119 instead of the wrapper provided by glibc,
122 system call would be invoked as follows on the ARM architecture with the EABI
123 in little endian mode:
127 syscall(SYS_readahead, fd, 0,
128 (unsigned int) (offset & 0xFFFFFFFF),
129 (unsigned int) (offset >> 32),
134 Since the offset argument is 64 bits, and the first argument
138 the caller must manually split and align the 64-bit value
139 so that it is passed in the
142 That means inserting a dummy value into
144 (the second argument of 0).
145 Care also must be taken so that the split follows endian conventions
146 (according to the C ABI for the platform).
148 Similar issues can occur on MIPS with the O32 ABI,
149 on PowerPC and parisc with the 32-bit ABI, and on Xtensa.
150 .\" Mike Frysinger: this issue ends up forcing MIPS
151 .\" O32 to take 7 arguments to syscall()
153 .\" See arch/parisc/kernel/sys_parisc.c.
154 Note that while the parisc C ABI also uses aligned register pairs,
155 it uses a shim layer to hide the issue from user space.
157 The affected system calls are
158 .BR fadvise64_64 (2),
160 .BR posix_fadvise (2),
164 .BR sync_file_range (2),
168 .\" You need to look up the syscalls directly in the kernel source to see if
169 .\" they should be in this list. For example, look at fs/read_write.c and
170 .\" the function signatures that do:
171 .\" ..., unsigned long, pos_l, unsigned long, pos_h, ...
172 .\" If they use off_t, then they most likely do not belong in this list.
173 This does not affect syscalls that manually split and assemble 64-bit values
181 Welcome to the wonderful world of historical baggage.
182 .SS Architecture calling conventions
183 Every architecture has its own way of invoking and passing arguments to the
185 The details for various architectures are listed in the two tables below.
187 The first table lists the instruction used to transition to kernel mode
188 (which might not be the fastest or best way to transition to the kernel,
189 so you might have to refer to
191 the register used to indicate the system call number,
192 the register(s) used to return the system call result,
193 and the register used to signal an error.
199 Arch/ABI Instruction System Ret Ret Error Notes
202 alpha callsys v0 v0 a4 a3 1, 6
204 arm/OABI swi NR - r0 - - 2
205 arm/EABI swi 0x0 r7 r0 r1 -
206 arm64 svc #0 w8 x0 x1 -
207 blackfin excpt 0x0 P0 R0 - -
208 i386 int $0x80 eax eax edx -
209 ia64 break 0x100000 r15 r8 r9 r10 1, 6
210 m68k trap #0 d0 d0 - -
211 microblaze brki r14,8 r12 r3 - -
212 mips syscall v0 v0 v1 a3 1, 6
213 nios2 trap r2 r2 - r7
214 parisc ble 0x100(%sr2, %r0) r20 r28 - -
215 powerpc sc r0 r3 - r0 1
216 powerpc64 sc r0 r3 - cr0.SO 1
217 riscv ecall a7 a0 a1 -
218 s390 svc 0 r1 r2 r3 - 3
219 s390x svc 0 r1 r2 r3 - 3
220 superh trap #0x17 r3 r0 r1 - 4, 6
221 sparc/32 t 0x10 g1 o0 o1 psr/csr 1, 6
222 sparc/64 t 0x6d g1 o0 o1 psr/csr 1, 6
223 tile swint1 R10 R00 - R01 1
224 x86-64 syscall rax rax rdx - 5
225 x32 syscall rax rax rdx - 5
226 xtensa syscall a2 a2 - -
231 On a few architectures,
232 a register is used as a boolean
233 (0 indicating no error, and \-1 indicating an error) to signal that the
235 The actual error value is still contained in the return register.
236 On sparc, the carry bit
238 in the processor status register
240 is used instead of a full register.
241 On powerpc64, the summary overflow bit
243 in field 0 of the condition register
248 is the system call number.
252 (the system call number) may be passed directly with
254 if it is less than 256.
256 On SuperH, the trap number controls the maximum number of arguments passed.
259 can be used with only 0-argument system calls, a
261 can be used with 0- or 1-argument system calls,
264 for 7-argument system calls.
266 The x32 ABI shares syscall table with x86-64 ABI, but there are some
270 In order to indicate that a system call is called under the x32 ABI,
272 .BR __X32_SYSCALL_BIT ,
273 is bitwise-ORed with the system call number.
274 The ABI used by a process affects some process behaviors,
275 including signal handling or system call restarting.
277 Since x32 has different sizes for
279 and pointer types, layouts of some (but not all;
283 are 64-bit, for example) structures are different.
284 In order to handle this,
285 additional system calls are added to the system call table,
286 starting from number 512
288 .BR __X32_SYSCALL_BIT ).
291 is defined as 19 for the x86-64 ABI and as
292 .IR __X32_SYSCALL_BIT " | " \fB515\fP
294 Most of these additional system calls are actually identical
295 to the system calls used for providing i386 compat.
296 There are some notable exceptions, however, such as
300 entities with 4-byte pointers and sizes ("compat_iovec" in kernel terms),
303 argument in a single register and not two, as is done in every other ABI.
307 (namely, Alpha, IA-64, MIPS, SuperH, sparc/32, and sparc/64)
308 use an additional register ("Retval2" in the above table)
309 to pass back a second return value from the
312 Alpha uses this technique in the architecture-specific
317 system calls as well.
318 Other architectures do not use the second return value register
319 in the system call interface, even if it is defined in the System V ABI.
325 The second table shows the registers used to pass the system call arguments.
330 l l2 l2 l2 l2 l2 l2 l2 l.
331 Arch/ABI arg1 arg2 arg3 arg4 arg5 arg6 arg7 Notes
333 alpha a0 a1 a2 a3 a4 a5 -
334 arc r0 r1 r2 r3 r4 r5 -
335 arm/OABI r0 r1 r2 r3 r4 r5 r6
336 arm/EABI r0 r1 r2 r3 r4 r5 r6
337 arm64 x0 x1 x2 x3 x4 x5 -
338 blackfin R0 R1 R2 R3 R4 R5 -
339 i386 ebx ecx edx esi edi ebp -
340 ia64 out0 out1 out2 out3 out4 out5 -
341 m68k d1 d2 d3 d4 d5 a0 -
342 microblaze r5 r6 r7 r8 r9 r10 -
343 mips/o32 a0 a1 a2 a3 - - - 1
344 mips/n32,64 a0 a1 a2 a3 a4 a5 -
345 nios2 r4 r5 r6 r7 r8 r9 -
346 parisc r26 r25 r24 r23 r22 r21 -
347 powerpc r3 r4 r5 r6 r7 r8 r9
348 powerpc64 r3 r4 r5 r6 r7 r8 -
349 riscv a0 a1 a2 a3 a4 a5 -
350 s390 r2 r3 r4 r5 r6 r7 -
351 s390x r2 r3 r4 r5 r6 r7 -
352 superh r4 r5 r6 r7 r0 r1 r2
353 sparc/32 o0 o1 o2 o3 o4 o5 -
354 sparc/64 o0 o1 o2 o3 o4 o5 -
355 tile R00 R01 R02 R03 R04 R05 -
356 x86-64 rdi rsi rdx r10 r8 r9 -
357 x32 rdi rsi rdx r10 r8 r9 -
358 xtensa a6 a3 a4 a5 a8 a9 -
363 The mips/o32 system call convention passes
364 arguments 5 through 8 on the user stack.
370 Note that these tables don't cover the entire calling convention\(emsome
371 architectures may indiscriminately clobber other registers not listed here.
376 #include <sys/syscall.h>
377 #include <sys/types.h>
381 main(int argc, char *argv[])
385 tid = syscall(SYS_gettid);
386 syscall(SYS_tgkill, getpid(), tid, SIGHUP);