man2/_syscall.2

   1 .\" Copyright (c) 1993 Michael Haardt (michael@moria.de),
   2 .\"   Fri Apr  2 11:32:09 MET DST 1993
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Tue Jul  6 12:42:46 MDT 1993 <dminer@nyx.cs.du.edu>
  26 .\" Added "Calling Directly" and supporting paragraphs
  27 .\"
  28 .\" Modified Sat Jul 24 15:19:12 1993 by Rik Faith <faith@cs.unc.edu>
  29 .\"
  30 .\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>:
  31 .\"   Added explanation of arg stacking when 6 or more args.
  32 .\"
  33 .\" Modified 10 June 1995 by Andries Brouwer <aeb@cwi.nl>
  34 .\"
  35 .\" 2007-10-23 mtk: created as a new page, by taking the content
  36 .\" specific to the _syscall() macros from intro(2).
  37 .\"
  38 .TH _SYSCALL 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  39 .SH NAME
  40 _syscall \- invoking a system call without library support (OBSOLETE)
  41 .SH SYNOPSIS
  42 .nf
  43 .B #include <linux/unistd.h>
  44 .PP
  45 A _syscall macro
  46 .PP
  47 desired system call
  48 .fi
  49 .SH DESCRIPTION
  50 The important thing to know about a system call is its prototype.
  51 You need to know how many arguments, their types,
  52 and the function return type.
  53 There are seven macros that make the actual call into the system easier.
  54 They have the form:
  55 .PP
  56 .in +4n
  57 .EX
  58 .RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...)
  59 .EE
  60 .in
  61 .PP
  62 where
  63 .IP
  64 .I X
  65 is 0\(en6, which are the number of arguments taken by the
  66 system call
  67 .IP
  68 .I type
  69 is the return type of the system call
  70 .IP
  71 .I name
  72 is the name of the system call
  73 .IP
  74 .I typeN
  75 is the Nth argument's type
  76 .IP
  77 .I argN
  78 is the name of the Nth argument
  79 .PP
  80 These macros create a function called
  81 .I name
  82 with the arguments you
  83 specify.
  84 Once you include the _syscall() in your source file,
  85 you call the system call by
  86 .IR name .
  87 .SH FILES
  88 .I /usr/include/linux/unistd.h
  89 .SH CONFORMING TO
  90 The use of these macros is Linux-specific, and deprecated.
  91 .SH NOTES
  92 Starting around kernel 2.6.18, the _syscall macros were removed
  93 from header files supplied to user space.
  94 Use
  95 .BR syscall (2)
  96 instead.
  97 (Some architectures, notably ia64, never provided the _syscall macros;
  98 on those architectures,
  99 .BR syscall (2)
 100 was always required.)
 101 .PP
 102 The _syscall() macros
 103 .I "do not"
 104 produce a prototype.
 105 You may have to
 106 create one, especially for C++ users.
 107 .PP
 108 System calls are not required to return only positive or negative error
 109 codes.
 110 You need to read the source to be sure how it will return errors.
 111 Usually, it is the negative of a standard error code,
 112 for example,
 113 .RI \- EPERM .
 114 The _syscall() macros will return the result
 115 .I r
 116 of the system call
 117 when
 118 .I r
 119 is nonnegative, but will return \-1 and set the variable
 120 .I errno
 121 to
 122 .RI \- r
 123 when
 124 .I r
 125 is negative.
 126 For the error codes, see
 127 .BR errno (3).
 128 .PP
 129 When defining a system call, the argument types
 130 .I must
 131 be
 132 passed by-value or by-pointer (for aggregates like structs).
 133 .\" The preferred way to invoke system calls that glibc does not know
 134 .\" about yet is via
 135 .\" .BR syscall (2).
 136 .\" However, this mechanism can be used only if using a libc
 137 .\" (such as glibc) that supports
 138 .\" .BR syscall (2),
 139 .\" and if the
 140 .\" .I <sys/syscall.h>
 141 .\" header file contains the required SYS_foo definition.
 142 .\" Otherwise, the use of a _syscall macro is required.
 143 .\"
 144 .SH EXAMPLES
 145 .EX
 146 #include <stdio.h>
 147 #include <stdlib.h>
 148 #include <errno.h>
 149 #include <linux/unistd.h>       /* for _syscallX macros/related stuff */
 150 #include <linux/kernel.h>       /* for struct sysinfo */
 151
 152 _syscall1(int, sysinfo, struct sysinfo *, info);
 153
 154 int
 155 main(void)
 156 {
 157     struct sysinfo s_info;
 158     int error;
 159
 160     error = sysinfo(&s_info);
 161     printf("code error = %d\en", error);
 162     printf("Uptime = %lds\enLoad: 1 min %lu / 5 min %lu / 15 min %lu\en"
 163            "RAM: total %lu / free %lu / shared %lu\en"
 164            "Memory in buffers = %lu\enSwap: total %lu / free %lu\en"
 165            "Number of processes = %d\en",
 166            s_info.uptime, s_info.loads[0],
 167            s_info.loads[1], s_info.loads[2],
 168            s_info.totalram, s_info.freeram,
 169            s_info.sharedram, s_info.bufferram,
 170            s_info.totalswap, s_info.freeswap,
 171            s_info.procs);
 172     exit(EXIT_SUCCESS);
 173 }
 174 .EE
 175 .SS Sample output
 176 .EX
 177 code error = 0
 178 uptime = 502034s
 179 Load: 1 min 13376 / 5 min 5504 / 15 min 1152
 180 RAM: total 15343616 / free 827392 / shared 8237056
 181 Memory in buffers = 5066752
 182 Swap: total 27881472 / free 24698880
 183 Number of processes = 40
 184 .EE
 185 .SH SEE ALSO
 186 .BR intro (2),
 187 .BR syscall (2),
 188 .BR errno (3)