huschi.net

SYSCALL(2)                 Linux Programmer's Manual                SYSCALL(2)

NAME
       syscall - indirect system call
SYNOPSIS
       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>
       #include <sys/syscall.h>   /* For SYS_xxx definitions */
       int syscall(int number, ...);
DESCRIPTION
       syscall()  is  a  small  library  function that invokes the system call
       whose assembly language interface has the  specified  number  with  the
       specified  arguments.  Employing syscall() is useful, for example, when
       invoking a system call that has no wrapper function in the C library.
       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 errno(3) if an error occurs.
       Symbolic constants for system call numbers can be found in  the  header
       file <sys/syscall.h>.
RETURN VALUE
       The  return value is defined by the system call being invoked.  In gen-
       eral, a 0 return value indicates success.  A -1 return value  indicates
       an error, and an error code is stored in errno.
NOTES
       syscall() first appeared in 4BSD.
   Architecture-specific requirements
       Each architecture ABI has its own requirements on how system call argu-
       ments 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 architec-
       ture.   However, when using 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., long long) must be  aligned  to  an  even  register  pair.
       Thus,  using  syscall()  instead  of the wrapper provided by glibc, the
       readahead() system call would be invoked as follows on the  ARM  archi-
       tecture with the EABI:
           syscall(SYS_readahead, fd, 0,
                   (unsigned int) (offset >> 32),
                   (unsigned int) (offset & 0xFFFFFFFF),
                   count);
       Since  the  offset  argument is 64 bits, and the first argument (fd) is
       passed in r0, the caller must manually split and align the 64-bit value
       so  that it is passed in the r2/r3 register pair.  That means inserting
       a dummy value into 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.
       The   affected   system   calls  are  fadvise64_64(2),  ftruncate64(2),
       posix_fadvise(2),      pread64(2),      pwrite64(2),      readahead(2),
       sync_file_range(2), and truncate64(2).
   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 the VDSO), the register used to
       indicate the system call number, and the register used  to  return  the
       system call result.
       arch/ABI   instruction          syscall #   retval Notes
       -----------------------------------------------------------------------------------
       arm/OABI   swi NR               -           a1     NR is syscall #
       arm/EABI   swi 0x0              r7          r1
       blackfin   excpt 0x0            P0          R0
       i386       int $0x80            eax         eax
       ia64       break 0x100000       r15         r10/r8
       parisc     ble 0x100(%sr2, %r0) r20         r28
       s390       svc 0                r1          r2     NR may be passed directly with
       s390x      svc 0                r1          r2     "svc NR" if NR is less than 256
       sparc/32   t 0x10               g1          o0
       sparc/64   t 0x6d               g1          o0
       x86_64     syscall              rax         rax
       The second table shows the registers used to pass the system call argu-
       ments.
       arch/ABI   arg1   arg2   arg3   arg4   arg5   arg6   arg7
       ----------------------------------------------------------
       arm/OABI   a1     a2     a3     a4     v1     v2     v3
       arm/EABI   r1     r2     r3     r4     r5     r6     r7
       blackfin   R0     R1     R2     R3     R4     R5     -
       i386       ebx    ecx    edx    esi    edi    ebp    -
       ia64       r11    r9     r10    r14    r15    r13    -
       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     -
       Note that these tables don't cover the entire calling  convention--some
       architectures  may  indiscriminately clobber other registers not listed
       here.
EXAMPLE
       #define _GNU_SOURCE
       #include <unistd.h>
       #include <sys/syscall.h>
       #include <sys/types.h>
       int
       main(int argc, char *argv[])
       {
           pid_t tid;
           tid = syscall(SYS_gettid);
           tid = syscall(SYS_tgkill, getpid(), tid);
       }
SEE ALSO
       _syscall(2), intro(2), syscalls(2)
COLOPHON
       This page is part of release 3.53 of the Linux  man-pages  project.   A
       description  of  the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.

Linux                             2013-06-21                        SYSCALL(2)