man2/_syscall.2

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