man2/_syscall.2

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