]>
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 | .\" | |
bf42aad4 | 40 | .TH SYSCALL 2 2012-08-14 "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 MK |
48 | |
49 | .BI "int syscall(int " number ", ...);" | |
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. | |
638fd4bf CH |
82 | |
83 | Each architecture ABI has its own requirements on how system call arguments are passed to the kernel. | |
84 | For system calls that have a glibc wrapper (i.g., most system calls) glibc handles the details of copy arguments to the right registers in a manner suitable for the architecture. | |
85 | However, when using | |
86 | .BR syscall () | |
87 | to make a system call, | |
88 | the caller may need to handle architecture-dependent details. | |
89 | For example, on ARM architecture, a | |
90 | .I "long long" | |
91 | argument is considered to be 8-byte aligned and to be split into two 4-byte arguments. | |
92 | ||
93 | .BR readahead () | |
94 | system call could be called like below in ARM architecture. | |
95 | ||
96 | syscall(__NR_readahead, fd, | |
97 | .I 0 | |
98 | , (unsigned int)( | |
99 | .I offset | |
100 | >> 32), (unsigned int)( | |
101 | .I offset | |
102 | & 0xFFFFFFFF), count) | |
103 | ||
104 | .I offset | |
105 | is 64 bit and should be 8-byte aligned. | |
106 | Thus, a padding is inserted before | |
107 | .I offset | |
108 | and | |
109 | .I offset | |
110 | is split into two 32 bit arguments. | |
111 | ||
c046a641 | 112 | .SH EXAMPLE |
c046a641 MK |
113 | .nf |
114 | #define _GNU_SOURCE | |
115 | #include <unistd.h> | |
116 | #include <sys/syscall.h> | |
117 | #include <sys/types.h> | |
118 | ||
119 | int | |
120 | main(int argc, char *argv[]) | |
121 | { | |
122 | pid_t tid; | |
863b571e | 123 | |
fa66abf8 | 124 | tid = syscall(SYS_gettid); |
498a96a2 | 125 | tid = syscall(SYS_tgkill, getpid(), tid); |
c046a641 MK |
126 | } |
127 | .fi | |
c58418c9 | 128 | .SH SEE ALSO |
0c2b92ba | 129 | .BR _syscall (2), |
f0c34053 | 130 | .BR intro (2), |
cc4615cc | 131 | .BR syscalls (2) |