]>
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 | .\" | |
95253016 | 40 | .TH SYSCALL 2 2013-04-01 "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 | 82 | |
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), | |
86 | glibc handles the details of copyiing arguments to the right registers | |
87 | in a manner suitable for the architecture. | |
638fd4bf CH |
88 | However, when using |
89 | .BR syscall () | |
90 | to make a system call, | |
91 | the caller may need to handle architecture-dependent details. | |
9e5c5e5f | 92 | For example, on the ARM architecture Embbeded ABI (EABI), a |
638fd4bf | 93 | .I "long long" |
9e5c5e5f MK |
94 | argument is considered to be 8-byte aligned and to be split |
95 | into two 4-byte arguments. | |
638fd4bf | 96 | |
95253016 | 97 | For example, the |
638fd4bf | 98 | .BR readahead () |
9e5c5e5f | 99 | system call would be invoked as follows on the ARM architecture with the EABI: |
638fd4bf | 100 | |
95253016 MK |
101 | .in +4n |
102 | .nf | |
103 | syscall(__NR_readahead, fd, 0, (unsigned int)(offset >> 32), | |
104 | (unsigned int)(offset & 0xFFFFFFFF), count); | |
105 | .fi | |
106 | .in | |
107 | .PP | |
638fd4bf CH |
108 | .I offset |
109 | is 64 bit and should be 8-byte aligned. | |
110 | Thus, a padding is inserted before | |
111 | .I offset | |
112 | and | |
113 | .I offset | |
95253016 | 114 | is split into two 32-bit arguments. |
9e5c5e5f MK |
115 | Similar issues can occur on MIPS with the O32 ABI and |
116 | on PowerPC with the 32-bit ABI. | |
117 | The affected system calls are | |
118 | .BR fadvise64_64 (2) | |
119 | .BR ftruncate64 (2) | |
120 | .BR pread64 (2) | |
121 | .BR pwrite64 (2) | |
122 | .BR readahead (2) | |
123 | and | |
124 | .BR truncate64 (2). | |
c046a641 | 125 | .SH EXAMPLE |
c046a641 MK |
126 | .nf |
127 | #define _GNU_SOURCE | |
128 | #include <unistd.h> | |
129 | #include <sys/syscall.h> | |
130 | #include <sys/types.h> | |
131 | ||
132 | int | |
133 | main(int argc, char *argv[]) | |
134 | { | |
135 | pid_t tid; | |
863b571e | 136 | |
fa66abf8 | 137 | tid = syscall(SYS_gettid); |
498a96a2 | 138 | tid = syscall(SYS_tgkill, getpid(), tid); |
c046a641 MK |
139 | } |
140 | .fi | |
c58418c9 | 141 | .SH SEE ALSO |
0c2b92ba | 142 | .BR _syscall (2), |
f0c34053 | 143 | .BR intro (2), |
cc4615cc | 144 | .BR syscalls (2) |