.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
+.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
+.\" %%%LICENSE_END
.\"
.\" @(#)syscall.2 8.1 (Berkeley) 6/16/93
.\"
.\"
.\" 2002-03-20 Christoph Hellwig <hch@infradead.org>
.\" - adopted for Linux
+.\" 2015-01-17, Kees Cook <keescook@chromium.org>
+.\" Added mips and arm64.
.\"
-.TH SYSCALL 2 2007-07-26 "Linux" "Linux Programmer's Manual"
+.TH SYSCALL 2 2015-01-22 "Linux" "Linux Programmer's Manual"
.SH NAME
syscall \- indirect system call
.SH SYNOPSIS
.nf
-.BR "#define _GNU_SOURCE " " /* or _BSD_SOURCE or _SVID_SOURCE */"
+.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <unistd.h>
.BR "#include <sys/syscall.h> " "/* For SYS_xxx definitions */"
-.BI "int syscall(int " number ", ...);"
+.BI "long syscall(long " number ", ...);"
.fi
.SH DESCRIPTION
.BR syscall ()
-performs the system call whose assembly language
+is a small library function that invokes
+the system call whose assembly language
interface has the specified
.I number
with the specified arguments.
-Symbolic constants for system calls can be found in the header file
+Employing
+.BR syscall ()
+is useful, for example,
+when invoking a system call that has no wrapper function in the C library.
+
+.BR syscall ()
+saves CPU registers before making the system call,
+restores the registers upon return from the system call,
+and stores any error code returned by the system call in
+.BR errno (3)
+if an error occurs.
+
+Symbolic constants for system call numbers can be found in the header file
.IR <sys/syscall.h> .
.SH RETURN VALUE
The return value is defined by the system call being invoked.
.BR syscall ()
first appeared in
4BSD.
+.SS Architecture-specific requirements
+Each architecture ABI has its own requirements on how
+system call arguments are passed to the kernel.
+For system calls that have a glibc wrapper (e.g., most system calls),
+glibc handles the details of copying arguments to the right registers
+in a manner suitable for the architecture.
+However, when using
+.BR syscall ()
+to make a system call,
+the caller might need to handle architecture-dependent details;
+this requirement is most commonly encountered on certain 32-bit architectures.
+
+For example, on the ARM architecture Embedded ABI (EABI), a
+64-bit value (e.g.,
+.IR "long long" )
+must be aligned to an even register pair.
+Thus, using
+.BR syscall ()
+instead of the wrapper provided by glibc,
+the
+.BR readahead ()
+system call would be invoked as follows on the ARM architecture with the EABI:
+
+.in +4n
+.nf
+syscall(SYS_readahead, fd, 0,
+ (unsigned int) (offset >> 32),
+ (unsigned int) (offset & 0xFFFFFFFF),
+ count);
+.fi
+.in
+.PP
+Since the offset argument is 64 bits, and the first argument
+.RI ( fd )
+is passed in
+.IR r0 ,
+the caller must manually split and align the 64-bit value
+so that it is passed in the
+.IR r2 / r3
+register pair.
+That means inserting a dummy value into
+.I r1
+(the second argument of 0).
+
+Similar issues can occur on MIPS with the O32 ABI,
+on PowerPC with the 32-bit ABI, and on Xtensa.
+.\" Mike Frysinger: this issue ends up forcing MIPS
+.\" O32 to take 7 arguments to syscall()
+
+The affected system calls are
+.BR fadvise64_64 (2),
+.BR ftruncate64 (2),
+.BR posix_fadvise (2),
+.BR pread64 (2),
+.BR pwrite64 (2),
+.BR readahead (2),
+.BR sync_file_range (2),
+and
+.BR truncate64 (2).
+.SS Architecture calling conventions
+Every architecture has its own way of invoking and passing arguments to the
+kernel.
+The details for various architectures are listed in the two tables below.
+
+The first table lists the instruction used to transition to kernel mode,
+(which might not be the fastest or best way to transition to the kernel,
+so you might have to refer to
+.BR vdso (7)),
+the register used to indicate the system call number,
+and the register used to return the system call result.
+.if t \{\
+.ft CW
+\}
+.TS
+l l1 l l1 l.
+arch/ABI instruction syscall # retval Notes
+_
+arm/OABI swi NR - a1 NR is syscall #
+arm/EABI swi 0x0 r7 r0
+arm64 svc #0 x8 x0
+blackfin excpt 0x0 P0 R0
+i386 int $0x80 eax eax
+ia64 break 0x100000 r15 r8 See below
+mips syscall v0 v0 See below
+parisc ble 0x100(%sr2, %r0) r20 r28
+s390 svc 0 r1 r2 See below
+s390x svc 0 r1 r2 See below
+sparc/32 t 0x10 g1 o0
+sparc/64 t 0x6d g1 o0
+x86_64 syscall rax rax
+.TE
+.PP
+For s390 and s390x, NR (the system call number)
+may be passed directly with "svc NR" if it is less than 256.
+
+On a few architectures,
+a register is used to indicate simple boolean failure of the system call:
+ia64 uses
+.I r10
+for this purpose,
+and mips uses
+.IR a3 .
+.if t \{\
+.in
+.ft P
+\}
+.PP
+The second table shows the registers used to pass the system call arguments.
+.if t \{\
+.ft CW
+\}
+.TS
+l l2 l2 l2 l2 l2 l2 l2 l.
+arch/ABI arg1 arg2 arg3 arg4 arg5 arg6 arg7 Notes
+_
+arm/OABI a1 a2 a3 a4 v1 v2 v3
+arm/EABI r0 r1 r2 r3 r4 r5 r6
+arm64 x0 x1 x2 x3 x4 x5 -
+blackfin R0 R1 R2 R3 R4 R5 -
+i386 ebx ecx edx esi edi ebp -
+ia64 out0 out1 out2 out3 out4 out5 -
+mips/o32 a0 a1 a2 a3 - - - See below
+mips/n32,64 a0 a1 a2 a3 a4 a5 -
+parisc r26 r25 r24 r23 r22 r21 -
+s390 r2 r3 r4 r5 r6 r7 -
+s390x r2 r3 r4 r5 r6 r7 -
+sparc/32 o0 o1 o2 o3 o4 o5 -
+sparc/64 o0 o1 o2 o3 o4 o5 -
+x86_64 rdi rsi rdx r10 r8 r9 -
+.TE
+.PP
+The mips/o32 system call convention passes
+arguments 5 through 8 on the user stack.
+.if t \{\
+.in
+.ft P
+\}
+.PP
+Note that these tables don't cover the entire calling convention\(emsome
+architectures may indiscriminately clobber other registers not listed here.
.SH EXAMPLE
.nf
#define _GNU_SOURCE
#include <unistd.h>
#include <sys/syscall.h>
#include <sys/types.h>
+#include <signal.h>
int
main(int argc, char *argv[])
pid_t tid;
tid = syscall(SYS_gettid);
+ tid = syscall(SYS_tgkill, getpid(), tid, SIGHUP);
}
.fi
.SH SEE ALSO
.BR _syscall (2),
.BR intro (2),
-.BR syscalls (2)
+.BR syscalls (2),
+.BR errno (3),
+.BR vdso (7)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.