original/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 2007-12-19 "Linux" "Linux Programmer's Manual"
  39 .SH NAME
  40 _syscall \- invoking a system call without library support (OBSOLETE)
  41 .SH SYNOPSIS
  42 .B #include <linux/unistd.h>
  43
  44 A _syscall macro
  45
  46 desired system call
  47 .SH DESCRIPTION
  48 The important thing to know about a system call is its prototype.
  49 You need to know how many arguments, their types,
  50 and the function return type.
  51 There are seven macros that make the actual call into the system easier.
  52 They have the form:
  53 .sp
  54 .RS
  55 .RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...)
  56 .RE
  57 .PP
  58 where
  59 .IP
  60 \fIX\fP is 0\(en6, which are the number of arguments taken by the
  61 system call
  62 .IP
  63 \fItype\fP is the return type of the system call
  64 .IP
  65 \fIname\fP is the name of the system call
  66 .IP
  67 \fItypeN\fP is the Nth argument's type
  68 .IP
  69 \fIargN\fP is the name of the Nth argument
  70 .PP
  71 These macros create a function called \fIname\fP with the arguments you
  72 specify.
  73 Once you include the _syscall() in your source file,
  74 you call the system call by \fIname\fP.
  75 .SH FILES
  76 .I /usr/include/linux/unistd.h
  77 .SH CONFORMING TO
  78 The use of these macros is Linux-specific, and deprecated.
  79 .SH NOTES
  80 Starting around kernel 2.6.18, the _syscall macros were removed
  81 from header files supplied to user space.
  82 Use
  83 .BR syscall (2)
  84 instead.
  85 (Some architectures, notably ia64, never provided the _syscall macros;
  86 on those architectures,
  87 .BR syscall (2)
  88 was always required.)
  89
  90 The _syscall() macros \fIdo not\fP produce a prototype.
  91 You may have to
  92 create one, especially for C++ users.
  93
  94 System calls are not required to return only positive or negative error
  95 codes.
  96 You need to read the source to be sure how it will return errors.
  97 Usually, it is the negative of a standard error code,
  98 for example, \-\fBEPERM\fP.
  99 The _syscall() macros will return the result \fIr\fP of the system call
 100 when \fIr\fP is nonnegative, but will return \-1 and set the variable
 101 .I errno
 102 to \-\fIr\fP when \fIr\fP is negative.
 103 For the error codes, see
 104 .BR errno (3).
 105
 106 When defining a system call, the argument types \fImust\fP be
 107 passed by-value or by-pointer (for aggregates like structs).
 108 .\" The preferred way to invoke system calls that glibc does not know
 109 .\" about yet is via
 110 .\" .BR syscall (2).
 111 .\" However, this mechanism can only be used if using a libc
 112 .\" (such as glibc) that supports
 113 .\" .BR syscall (2),
 114 .\" and if the
 115 .\" .I <sys/syscall.h>
 116 .\" header file contains the required SYS_foo definition.
 117 .\" Otherwise, the use of a _syscall macro is required.
 118 .\"
 119 .SH EXAMPLE
 120 .nf
 121 #include <stdio.h>
 122 #include <stdlib.h>
 123 #include <errno.h>
 124 #include <linux/unistd.h>       /* for _syscallX macros/related stuff */
 125 #include <linux/kernel.h>       /* for struct sysinfo */
 126
 127 _syscall1(int, sysinfo, struct sysinfo *, info);
 128
 129 /* Note: if you copy directly from the nroff source, remember to
 130 REMOVE the extra backslashes in the printf statement. */
 131
 132 int
 133 main(void)
 134 {
 135     struct sysinfo s_info;
 136     int error;
 137
 138     error = sysinfo(&s_info);
 139     printf("code error = %d\\n", error);
 140     printf("Uptime = %lds\\nLoad: 1 min %lu / 5 min %lu / 15 min %lu\\n"
 141            "RAM: total %lu / free %lu / shared %lu\\n"
 142            "Memory in buffers = %lu\\nSwap: total %lu / free %lu\\n"
 143            "Number of processes = %d\\n",
 144            s_info.uptime, s_info.loads[0],
 145            s_info.loads[1], s_info.loads[2],
 146            s_info.totalram, s_info.freeram,
 147            s_info.sharedram, s_info.bufferram,
 148            s_info.totalswap, s_info.freeswap,
 149            s_info.procs);
 150     exit(EXIT_SUCCESS);
 151 }
 152 .fi
 153 .SS Sample output
 154 .nf
 155 code error = 0
 156 uptime = 502034s
 157 Load: 1 min 13376 / 5 min 5504 / 15 min 1152
 158 RAM: total 15343616 / free 827392 / shared 8237056
 159 Memory in buffers = 5066752
 160 Swap: total 27881472 / free 24698880
 161 Number of processes = 40
 162 .fi
 163 .SH SEE ALSO
 164 .BR intro (2),
 165 .BR syscall (2),
 166 .BR errno (3)