Debian Codegraph @

upstream/debian-unstable/man2/_syscall.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
4 .\"
5 .TH _syscall 2 2025-05-17 "Linux man-pages 6.18"
6 .SH NAME
7 _syscall \- invoking a system call without library support (OBSOLETE)
8 .SH SYNOPSIS
9 .nf
10 .B #include <linux/unistd.h>
11 .P
12 A _syscall macro
13 .P
14 desired system call
15 .fi
16 .SH DESCRIPTION
17 The important thing to know about a system call is its prototype.
18 You need to know how many arguments, their types,
19 and the function return type.
20 There are seven macros that make the actual call into the system easier.
21 They have the form:
22 .P
23 .in +4n
24 .EX
25 .RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...)
26 .EE
27 .in
28 .P
29 where
30 .IP
31 .I X
32 is 0\[en]6, which are the number of arguments taken by the
33 system call
34 .IP
35 .I type
36 is the return type of the system call
37 .IP
38 .I name
39 is the name of the system call
40 .IP
41 .I typeN
42 is the Nth argument's type
43 .IP
44 .I argN
45 is the name of the Nth argument
46 .P
47 These macros create a function called
48 .I name
49 with the arguments you
50 specify.
51 Once you include the _syscall() in your source file,
52 you call the system call by
53 .IR name .
54 .SH FILES
55 .I /usr/include/linux/unistd.h
56 .SH STANDARDS
57 Linux.
58 .SH HISTORY
59 Starting around Linux 2.6.18, the _syscall macros were removed
60 from header files supplied to user space.
61 Use
62 .BR syscall (2)
63 instead.
64 (Some architectures, notably ia64, never provided the _syscall macros;
65 on those architectures,
66 .BR syscall (2)
67 was always required.)
68 .SH NOTES
69 The _syscall() macros
70 .I "do not"
71 produce a prototype.
72 You may have to
73 create one, especially for C++ users.
74 .P
75 System calls are not required to return only positive or negative error
76 codes.
77 You need to read the source to be sure how it will return errors.
78 Usually, it is the negative of a standard error code,
79 for example,
80 .RI \- EPERM .
81 The _syscall() macros will return the result
82 .I r
83 of the system call
84 when
85 .I r
86 is nonnegative, but will return \-1 and set the variable
87 .I errno
88 to
89 .RI \- r
90 when
91 .I r
92 is negative.
93 For the error codes, see
94 .BR errno (3).
95 .P
96 When defining a system call, the argument types
97 .I must
98 be
99 passed by-value or by-pointer (for aggregates like structs).
100 .\" The preferred way to invoke system calls that glibc does not know
101 .\" about yet is via
102 .\" .BR syscall (2).
103 .\" However, this mechanism can be used only if using a libc
104 .\" (such as glibc) that supports
105 .\" .BR syscall (2),
106 .\" and if the
107 .\" .I <sys/syscall.h>
108 .\" header file contains the required SYS_foo definition.
109 .\" Otherwise, the use of a _syscall macro is required.
110 .\"
111 .SH EXAMPLES
112 .\" SRC BEGIN (_syscall.c)
113 .EX
114 #include <stdio.h>
115 #include <stdlib.h>
116 #include <errno.h>
117 #include <linux/unistd.h> /* for _syscallX macros/related stuff */
118 #include <linux/kernel.h> /* for struct sysinfo */
119 \&
120 _syscall1(int, sysinfo, struct sysinfo *, info);
121 \&
122 int
123 main(void)
124 {
125 struct sysinfo s_info;
126 int error;
127 \&
128 error = sysinfo(&s_info);
129 printf("code error = %d\[rs]n", error);
130 printf("Uptime = %lds\[rs]nLoad: 1 min %lu / 5 min %lu / 15 min %lu\[rs]n"
131 "RAM: total %lu / free %lu / shared %lu\[rs]n"
132 "Memory in buffers = %lu\[rs]nSwap: total %lu / free %lu\[rs]n"
133 "Number of processes = %d\[rs]n",
134 s_info.uptime, s_info.loads[0],
135 s_info.loads[1], s_info.loads[2],
136 s_info.totalram, s_info.freeram,
137 s_info.sharedram, s_info.bufferram,
138 s_info.totalswap, s_info.freeswap,
139 s_info.procs);
140 exit(EXIT_SUCCESS);
141 }
142 .EE
143 .\" SRC END
144 .SS Sample output
145 .EX
146 code error = 0
147 uptime = 502034s
148 Load: 1 min 13376 / 5 min 5504 / 15 min 1152
149 RAM: total 15343616 / free 827392 / shared 8237056
150 Memory in buffers = 5066752
151 Swap: total 27881472 / free 24698880
152 Number of processes = 40
153 .EE
154 .SH SEE ALSO
155 .BR intro (2),
156 .BR syscall (2),
157 .BR errno (3)