INTRO(2)

NAME
intro - Introduction to system calls

DESCRIPTION
This chapter describes Linux system calls.

  Calling Directly
In most cases, it is unnecessary to invoke a system call directly, but there are times with the Standard C library does not implement a nice function call for you.

  Synopsis
#include <linux/unistd.h> desired system call A _syscall macro

  Setup
The important thing to know about a system call is its prototype. You need to know how many arguments, their types, and the function return type. There are six macros that make the actual call into the system easier. They have the form:

    _syscallX(type,name,atype,a)

        where X is 0–5, which are the number of arguments taken by the system call

        type is the return type of the system call

        name is the name of the system call

        atype is the first argument's type

        a is the name of the first argument

These macros create a function called name with the arguments you specify. Once you include the _syscall() in your source file, you call the system call by name.

EXAMPLE

#include <stdio.h>
#include <linux/unistd.h>	/* for _syscallX macros/related stuff */
#include <linux/kernel.h>	/* for struct sysinfo */
_syscall1(int, sysinfo, struct sysinfo *, info);
/* Note, if copy directly from the nroff source; remember, to
REMOVE the extra backslashes in the printf statement.                */
int main(void)
{
	struct sysinfo s_info;
	int error;
	error = sysinfo(&s_info);
	printf("code error = %d\n", error);
	printf("uptime = %d\n1 min load = %d\n5 min load = %d\n"
		"15 min load = %d\nTotal ram = %d\nFree ram = %d\n"
		"shared ram = %d\nMemory in buffers = %d\nTotal swap = %d\n"
		"Free swap = %d\nNumber of processes = %d\n",
		s_info.uptime, s_info.loads[0],
		s_info.loads[1], s_info.loads[2],
		s_info.totalram, s_info.freeram,
		s_info.sharedram, s_info.bufferram,
		s_info.totalswap, s_info.freeswap,
		s_info.procs);
	return(0);
}

Sample Output
code error = 0
uptime = 147851
1 min load = 0
5 min load = 0
15 min load = 0
Total ram = 5238784
Free ram = 495616
shared ram = 1191936
Memory in buffers = 2965504
Total swap = 5218304
Free swap = 4849664
Number of processes = 14

NOTES
The _syscall() macros DO NOT produce a prototype. You may have to create one, especially for C++ users.

System calls are not required to return only positive or negative error codes. You need to read the source to be sure how it will return errors. Usually, it is the negative of a standard error code. i.e., -EPERM.

Some system calls, such as mmap, require more than five arguments. These are handled by pushing the arguments on the stack and passing a pointer to the block of arguments.

When defining a system call, the arguments types MUST be passed by-value or by-pointer (for aggregates like structs).

FILES
linux/include/linux/unistd.h		or
/usr/include/linux/unistd.h

AUTHORS
Look at the header of the manual page for the author(s) and copyright conditions. Note that these can be different from page to page!