]>
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 | |
39 | .\" | |
0649afd4 | 40 | .TH SYSCALL 2 2014-12-31 "Linux" "Linux Programmer's Manual" |
c046a641 MK |
41 | .SH NAME |
42 | syscall \- indirect system call | |
43 | .SH SYNOPSIS | |
44 | .nf | |
b80f966b | 45 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
c046a641 | 46 | .B #include <unistd.h> |
cc4615cc | 47 | .BR "#include <sys/syscall.h> " "/* For SYS_xxx definitions */" |
c046a641 | 48 | |
24313b88 | 49 | .BI "long syscall(long " number ", ...);" |
c046a641 MK |
50 | .fi |
51 | .SH DESCRIPTION | |
52 | .BR syscall () | |
498a96a2 MK |
53 | is a small library function that invokes |
54 | the system call whose assembly language | |
fea681da | 55 | interface has the specified |
c046a641 | 56 | .I number |
fea681da | 57 | with the specified arguments. |
498a96a2 MK |
58 | Employing |
59 | .BR syscall () | |
60 | is useful, for example, | |
61 | when invoking a system call that has no wrapper function in the C library. | |
62 | ||
63 | .BR syscall () | |
64 | saves CPU registers before making the system call, | |
65 | restores the registers upon return from the system call, | |
66 | and stores any error code returned by the system call in | |
67 | .BR errno (3) | |
68 | if an error occurs. | |
69 | ||
70 | Symbolic constants for system call numbers can be found in the header file | |
c046a641 MK |
71 | .IR <sys/syscall.h> . |
72 | .SH RETURN VALUE | |
fea681da MK |
73 | The return value is defined by the system call being invoked. |
74 | In general, a 0 return value indicates success. | |
8729177b | 75 | A \-1 return value indicates an error, |
fea681da | 76 | and an error code is stored in |
c046a641 MK |
77 | .IR errno . |
78 | .SH NOTES | |
79 | .BR syscall () | |
80 | first appeared in | |
81 | 4BSD. | |
bed6b26e | 82 | .SS Architecture-specific requirements |
95253016 MK |
83 | Each architecture ABI has its own requirements on how |
84 | system call arguments are passed to the kernel. | |
85 | For system calls that have a glibc wrapper (e.g., most system calls), | |
bed6b26e | 86 | glibc handles the details of copying arguments to the right registers |
95253016 | 87 | in a manner suitable for the architecture. |
638fd4bf CH |
88 | However, when using |
89 | .BR syscall () | |
90 | to make a system call, | |
bed6b26e MK |
91 | the caller might need to handle architecture-dependent details; |
92 | this requirement is most commonly encountered on certain 32-bit architectures. | |
638fd4bf | 93 | |
bed6b26e MK |
94 | For example, on the ARM architecture Embedded ABI (EABI), a |
95 | 64-bit value (e.g., | |
96 | .IR "long long" ) | |
97 | must be aligned to an even register pair. | |
98 | Thus, using | |
99 | .BR syscall () | |
100 | instead of the wrapper provided by glibc, | |
101 | the | |
638fd4bf | 102 | .BR readahead () |
9e5c5e5f | 103 | system call would be invoked as follows on the ARM architecture with the EABI: |
638fd4bf | 104 | |
95253016 MK |
105 | .in +4n |
106 | .nf | |
bed6b26e MK |
107 | syscall(SYS_readahead, fd, 0, |
108 | (unsigned int) (offset >> 32), | |
109 | (unsigned int) (offset & 0xFFFFFFFF), | |
110 | count); | |
95253016 MK |
111 | .fi |
112 | .in | |
113 | .PP | |
bed6b26e MK |
114 | Since the offset argument is 64 bits, and the first argument |
115 | .RI ( fd ) | |
116 | is passed in | |
117 | .IR r0 , | |
ca972ff9 MK |
118 | the caller must manually split and align the 64-bit value |
119 | so that it is passed in the | |
bed6b26e MK |
120 | .IR r2 / r3 |
121 | register pair. | |
122 | That means inserting a dummy value into | |
123 | .I r1 | |
124 | (the second argument of 0). | |
125 | ||
126 | Similar issues can occur on MIPS with the O32 ABI, | |
127 | on PowerPC with the 32-bit ABI, and on Xtensa. | |
128 | .\" Mike Frysinger: this issue ends up forcing MIPS | |
129 | .\" O32 to take 7 arguments to syscall() | |
130 | ||
9e5c5e5f | 131 | The affected system calls are |
bed6b26e MK |
132 | .BR fadvise64_64 (2), |
133 | .BR ftruncate64 (2), | |
134 | .BR posix_fadvise (2), | |
135 | .BR pread64 (2), | |
136 | .BR pwrite64 (2), | |
137 | .BR readahead (2), | |
138 | .BR sync_file_range (2), | |
9e5c5e5f MK |
139 | and |
140 | .BR truncate64 (2). | |
08c9b3b9 MK |
141 | .SS Architecture calling conventions |
142 | Every architecture has its own way of invoking and passing arguments to the | |
143 | kernel. | |
144 | The details for various architectures are listed in the two tables below. | |
145 | ||
146 | The first table lists the instruction used to transition to kernel mode, | |
147 | (which might not be the fastest or best way to transition to the kernel, | |
951ae9c0 MF |
148 | so you might have to refer to |
149 | .BR vdso (7)), | |
08c9b3b9 MK |
150 | the register used to indicate the system call number, |
151 | and the register used to return the system call result. | |
152 | .if t \{\ | |
153 | .ft CW | |
154 | \} | |
155 | .TS | |
156 | l l1 l l1 l. | |
157 | arch/ABI instruction syscall # retval Notes | |
158 | _ | |
159 | arm/OABI swi NR - a1 NR is syscall # | |
aa60c0d2 | 160 | arm/EABI swi 0x0 r7 r0 |
08c9b3b9 MK |
161 | blackfin excpt 0x0 P0 R0 |
162 | i386 int $0x80 eax eax | |
19a225b0 MK |
163 | ia64 break 0x100000 r15 r10/r8 T{ |
164 | bool error/ | |
165 | .br | |
166 | errno value | |
167 | T} | |
08c9b3b9 | 168 | parisc ble 0x100(%sr2, %r0) r20 r28 |
19a225b0 MK |
169 | s390 svc 0 r1 r2 See below |
170 | s390x svc 0 r1 r2 See below | |
08c9b3b9 | 171 | sparc/32 t 0x10 g1 o0 |
202f5bfb | 172 | sparc/64 t 0x6d g1 o0 |
08c9b3b9 MK |
173 | x86_64 syscall rax rax |
174 | .TE | |
19a225b0 MK |
175 | .PP |
176 | For s390 and s390x, NR (the system call number) | |
177 | may be passed directly with "svc NR" if it is less than 256. | |
08c9b3b9 MK |
178 | .if t \{\ |
179 | .in | |
180 | .ft P | |
181 | \} | |
182 | .PP | |
183 | The second table shows the registers used to pass the system call arguments. | |
184 | .if t \{\ | |
185 | .ft CW | |
186 | \} | |
187 | .TS | |
188 | l l l l l l l l. | |
189 | arch/ABI arg1 arg2 arg3 arg4 arg5 arg6 arg7 | |
190 | _ | |
191 | arm/OABI a1 a2 a3 a4 v1 v2 v3 | |
aa60c0d2 | 192 | arm/EABI r0 r1 r2 r3 r4 r5 r6 |
08c9b3b9 MK |
193 | blackfin R0 R1 R2 R3 R4 R5 - |
194 | i386 ebx ecx edx esi edi ebp - | |
5e164192 | 195 | ia64 out0 out1 out2 out3 out4 out5 - |
08c9b3b9 | 196 | parisc r26 r25 r24 r23 r22 r21 - |
202f5bfb MF |
197 | s390 r2 r3 r4 r5 r6 r7 - |
198 | s390x r2 r3 r4 r5 r6 r7 - | |
08c9b3b9 MK |
199 | sparc/32 o0 o1 o2 o3 o4 o5 - |
200 | sparc/64 o0 o1 o2 o3 o4 o5 - | |
201 | x86_64 rdi rsi rdx r10 r8 r9 - | |
202 | .TE | |
203 | .if t \{\ | |
204 | .in | |
205 | .ft P | |
206 | \} | |
207 | .PP | |
208 | Note that these tables don't cover the entire calling convention\(emsome | |
209 | architectures may indiscriminately clobber other registers not listed here. | |
c046a641 | 210 | .SH EXAMPLE |
c046a641 MK |
211 | .nf |
212 | #define _GNU_SOURCE | |
213 | #include <unistd.h> | |
214 | #include <sys/syscall.h> | |
215 | #include <sys/types.h> | |
415f7e63 | 216 | #include <signal.h> |
c046a641 MK |
217 | |
218 | int | |
219 | main(int argc, char *argv[]) | |
220 | { | |
221 | pid_t tid; | |
863b571e | 222 | |
fa66abf8 | 223 | tid = syscall(SYS_gettid); |
415f7e63 | 224 | tid = syscall(SYS_tgkill, getpid(), tid, SIGHUP); |
c046a641 MK |
225 | } |
226 | .fi | |
c58418c9 | 227 | .SH SEE ALSO |
0c2b92ba | 228 | .BR _syscall (2), |
f0c34053 | 229 | .BR intro (2), |
951ae9c0 | 230 | .BR syscalls (2), |
4e0b8e82 | 231 | .BR errno (3), |
951ae9c0 | 232 | .BR vdso (7) |