intro(2)

1INTRO(2)                   Linux Programmer's Manual                  INTRO(2)
2
3
4

NAME

6       intro, _syscall - Introduction to system calls
7

DESCRIPTION

9       This  chapter  describes the Linux system calls.  For a list of the 164
10       syscalls present in Linux 2.0, see syscalls(2).
11
12   Calling Directly
13       In most cases, it is unnecessary to invoke a system call directly,  but
14       there  are  times when the Standard C library does not implement a nice
15       function call for you.  In this  case,  the  programmer  must  manually
16       invoke  the  system  call  using  either one of the _syscall macros, or
17       syscall().  The latter technique is described in syscall(2).  This page
18       describes  the  _syscall macros, and includes some notes on when to use
19       one or other mechanism.
20
21   Synopsis
22       #include <linux/unistd.h>
23
24       A _syscall macro
25
26       desired system call
27
28
29   Setup
30       The important thing to know about a system call is its prototype.   You
31       need  to  know how many arguments, their types, and the function return
32       type.  There are six macros that make the actual call into  the  system
33       easier.  They have the form:
34
35              _syscallX(type,name,type1,arg1,type2,arg2,...)
36
37                     where  X  is 0–5, which are the number of arguments taken
38                            by the system call
39
40                     type is the return type of the system call
41
42                     name is the name of the system call
43
44                     typeN is the Nth argument's type
45
46                     argN is the name of the Nth argument
47
48       These macros create a function called name with the arguments you spec‐
49       ify.  Once you include the _syscall() in your source file, you call the
50       system call by name.
51

EXAMPLE

53       #include <stdio.h>
54       #include <errno.h>
55       #include <linux/unistd.h>     /* for _syscallX macros/related stuff */
56       #include <linux/kernel.h>     /* for struct sysinfo */
57
58       _syscall1(int, sysinfo, struct sysinfo *, info);
59
60       /* Note: if you copy directly from the nroff source, remember to
61       REMOVE the extra backslashes in the printf statement. */
62
63       int main(void)
64       {
65            struct sysinfo s_info;
66            int error;
67
68            error = sysinfo(&s_info);
69            printf("code error = %d\n", error);
70               printf("Uptime = %lds\nLoad: 1 min %lu / 5 min %lu / 15 min %lu\n"
71                       "RAM: total %lu / free %lu / shared %lu\n"
72                       "Memory in buffers = %lu\nSwap: total %lu / free %lu\n"
73                       "Number of processes = %d\n",
74                 s_info.uptime, s_info.loads[0],
75                 s_info.loads[1], s_info.loads[2],
76                 s_info.totalram, s_info.freeram,
77                 s_info.sharedram, s_info.bufferram,
78                 s_info.totalswap, s_info.freeswap,
79                 s_info.procs);
80            return(0);
81       }
82
83   Sample Output
84       code error = 0
85       uptime = 502034s
86       Load: 1 min 13376 / 5 min 5504 / 15 min 1152
87       RAM: total 15343616 / free 827392 / shared 8237056
88       Memory in buffers = 5066752
89       Swap: total 27881472 / free 24698880
90       Number of processes = 40
91

NOTES

93       The _syscall() macros DO NOT produce a prototype.  You may have to cre‐
94       ate one, especially for C++ users.
95
96       System calls are not required to return only positive or negative error
97       codes.  You need to read the source to  be  sure  how  it  will  return
98       errors.   Usually,  it  is the negative of a standard error code, e.g.,
99       -EPERM.  The _syscall() macros will return the result r of  the  system
100       call  when  r  is  nonnegative, but will return -1 and set the variable
101       errno to -r when r is negative.  For the error codes, see errno(3).
102
103       Some system calls, such as mmap(), require more  than  five  arguments.
104       These  are  handled by pushing the arguments on the stack and passing a
105       pointer to the block of arguments.
106
107       When defining a system call, the argument types MUST be passed by-value
108       or by-pointer (for aggregates like structs).
109
110       The preferred way to invoke system calls that glibc does not know about
111       yet is via syscall(2).  However, this mechanism can  only  be  used  if
112       using  a  libc  (such  as  glibc)  that supports syscall(2), and if the
113       <sys/syscall.h> header file contains the required  SYS_foo  definition.
114       Otherwise, the use of a _syscall macro is required.
115
116       Some  architectures,  notably ia64, do not provide the _syscall macros.
117       On these architectures, syscall(2) must be used.
118

CONFORMING TO

120       Certain codes are used to indicate Unix variants and standards to which
121       calls in the section conform.  See standards(7).
122

FILES

124       /usr/include/linux/unistd.h
125

NAME

DESCRIPTION

EXAMPLE

NOTES

CONFORMING TO

FILES

SEE ALSO