1SYSCALL(2)                 Linux Programmer's Manual                SYSCALL(2)
2
3
4

NAME

6       syscall - indirect system call
7

SYNOPSIS

9       #define _GNU_SOURCE         /* See feature_test_macros(7) */
10       #include <unistd.h>
11       #include <sys/syscall.h>   /* For SYS_xxx definitions */
12
13       int syscall(int number, ...);
14

DESCRIPTION

16       syscall()  is  a  small  library  function that invokes the system call
17       whose assembly language interface has the  specified  number  with  the
18       specified  arguments.  Employing syscall() is useful, for example, when
19       invoking a system call that has no wrapper function in the C library.
20
21       syscall() saves CPU registers before making the system  call,  restores
22       the  registers  upon  return from the system call, and stores any error
23       code returned by the system call in errno(3) if an error occurs.
24
25       Symbolic constants for system call numbers can be found in  the  header
26       file <sys/syscall.h>.
27

RETURN VALUE

29       The  return value is defined by the system call being invoked.  In gen‐
30       eral, a 0 return value indicates success.  A -1 return value  indicates
31       an error, and an error code is stored in errno.
32

NOTES

34       syscall() first appeared in 4BSD.
35
36   Architecture-specific requirements
37       Each architecture ABI has its own requirements on how system call argu‐
38       ments are passed to the kernel.  For system calls  that  have  a  glibc
39       wrapper (e.g., most system calls), glibc handles the details of copying
40       arguments to the right registers in a manner suitable for the architec‐
41       ture.   However, when using syscall() to make a system call, the caller
42       might need to handle architecture-dependent details;  this  requirement
43       is most commonly encountered on certain 32-bit architectures.
44
45       For  example,  on  the  ARM  architecture Embedded ABI (EABI), a 64-bit
46       value (e.g., long long) must be  aligned  to  an  even  register  pair.
47       Thus,  using  syscall()  instead  of the wrapper provided by glibc, the
48       readahead() system call would be invoked as follows on the  ARM  archi‐
49       tecture with the EABI:
50
51           syscall(SYS_readahead, fd, 0,
52                   (unsigned int) (offset >> 32),
53                   (unsigned int) (offset & 0xFFFFFFFF),
54                   count);
55
56       Since  the  offset  argument is 64 bits, and the first argument (fd) is
57       passed in r0, the caller must manually split and align the 64-bit value
58       so  that it is passed in the r2/r3 register pair.  That means inserting
59       a dummy value into r1 (the second argument of 0).
60
61       Similar issues can occur on MIPS with the O32 ABI, on PowerPC with  the
62       32-bit ABI, and on Xtensa.
63
64       The   affected   system   calls  are  fadvise64_64(2),  ftruncate64(2),
65       posix_fadvise(2),      pread64(2),      pwrite64(2),      readahead(2),
66       sync_file_range(2), and truncate64(2).
67
68   Architecture calling conventions
69       Every architecture has its own way of invoking and passing arguments to
70       the kernel.  The details for various architectures are  listed  in  the
71       two tables below.
72
73       The  first  table  lists  the  instruction used to transition to kernel
74       mode, (which might not be the fastest or best way to transition to  the
75       kernel,  so  you might have to refer to the VDSO), the register used to
76       indicate the system call number, and the register used  to  return  the
77       system call result.
78
79       arch/ABI   instruction          syscall #   retval Notes
80       ───────────────────────────────────────────────────────────────────────────────────
81       arm/OABI   swi NR               -           a1     NR is syscall #
82       arm/EABI   swi 0x0              r7          r1
83       blackfin   excpt 0x0            P0          R0
84       i386       int $0x80            eax         eax
85       ia64       break 0x100000       r15         r10/r8
86       parisc     ble 0x100(%sr2, %r0) r20         r28
87       s390       svc 0                r1          r2     NR may be passed directly with
88       s390x      svc 0                r1          r2     "svc NR" if NR is less than 256
89       sparc/32   t 0x10               g1          o0
90       sparc/64   t 0x6d               g1          o0
91       x86_64     syscall              rax         rax
92
93       The second table shows the registers used to pass the system call argu‐
94       ments.
95
96       arch/ABI   arg1   arg2   arg3   arg4   arg5   arg6   arg7
97       ──────────────────────────────────────────────────────────
98       arm/OABI   a1     a2     a3     a4     v1     v2     v3
99       arm/EABI   r1     r2     r3     r4     r5     r6     r7
100       blackfin   R0     R1     R2     R3     R4     R5     -
101       i386       ebx    ecx    edx    esi    edi    ebp    -
102       ia64       r11    r9     r10    r14    r15    r13    -
103       parisc     r26    r25    r24    r23    r22    r21    -
104       s390       r2     r3     r4     r5     r6     r7     -
105       s390x      r2     r3     r4     r5     r6     r7     -
106       sparc/32   o0     o1     o2     o3     o4     o5     -
107       sparc/64   o0     o1     o2     o3     o4     o5     -
108       x86_64     rdi    rsi    rdx    r10    r8     r9     -
109
110       Note that these tables don't cover the entire  calling  convention—some
111       architectures  may  indiscriminately clobber other registers not listed
112       here.
113

EXAMPLE

115       #define _GNU_SOURCE
116       #include <unistd.h>
117       #include <sys/syscall.h>
118       #include <sys/types.h>
119
120       int
121       main(int argc, char *argv[])
122       {
123           pid_t tid;
124
125           tid = syscall(SYS_gettid);
126           tid = syscall(SYS_tgkill, getpid(), tid);
127       }
128

SEE ALSO

130       _syscall(2), intro(2), syscalls(2)
131

COLOPHON

133       This page is part of release 3.53 of the Linux  man-pages  project.   A
134       description  of  the project, and information about reporting bugs, can
135       be found at http://www.kernel.org/doc/man-pages/.
136
137
138
139Linux                             2013-06-21                        SYSCALL(2)
Impressum