Part II:

System Calls

intro

intro—Introduction to system calls

DESCRIPTION

This chapter describes the Linux system calls.

CALLING DIRECTLY

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

SYNOPSIS

#include <linux/unistd.h>

A _syscall macro
Desired system call

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. Six macros make the actual call into the system easier. They have the form

syscallX(type,name,type1,arg1,type2,arg2,...)

where

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

EXAMPLE

{

            struct sysinfo s_info;

            int error;



            error = sysinfo(&s_info);

            printf("code error = %d\n", error);

            printf("Uptime = %ds\nLoad: 1 min %d / 5 min %d / 15 min %d\n"

                       "RAM: total %d / free %d / shared %d\n"

                       "Memory in buffers = %d\nSwap: total %d / free  %d\n"

                       "Number 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 = 502034s

Load: 1 min 13376 / 5 min 5504 / 15 min 1152

RAM: total 15343616 / free 827392 / shared 8237056

Memory in buffers = 5066752

Swap: total 27881472 / free 24698880

Number of processes = 40

NOTES

The _syscall() macros do not produce a prototype. You might 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, for example, _EPERM. The _syscall() macros will return the result r of the system call when r is nonnegative, but will return _1 and set the variable errno to _r when r is negative.

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 argument types must be passed by value or by pointer (for aggregates such as structs).

FILES

/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.

Linux 1.2.13, 22 May 1996

exit

exit—Terminate the current process

SYNOPSIS

#include <unistd.h>

void exit(int status);

DESCRIPTION

exit terminates the calling process immediately. Any open file descriptors belonging to the process are closed; any children of the process are inherited by process 1, init, and the process's parent is sent a SIGCHLD signal.

status is returned to the parent process as the process's exit status and can be collected using one of the wait family of calls.

RETURN VALUE

exit never returns.

CONFORMS TO

SVID, AT&T, POSIX, X/OPEN, BSD 4.3

NOTES

exit does not call any functions registered with the ANSI C atexit function and does not flush standard I/O buffers. To do these things, use exit(3).

SEE ALSO

fork(2), execve(2), waitpid(2), wait4(2), kill(2), wait(3), exit(3)

Linux, 21 July 1993

accept

accept—Accept a connection on a socket

SYNOPSIS

#include <sys/types.h>

#include <sys/socket.h>

int accept(int s, struct sockaddr *addr,int*addrlen);

DESCRIPTION

The argument s is a socket that has been created with socket(2), bound to an address with bind(2), and is listening for connections after a listen(2). The accept function extracts the first connection request on the queue of pending connections, creates a new socket with the same properties of s, and allocates a new file descriptor for the socket. If no pending connections are present on the queue and the socket is not marked as nonblocking, accept blocks the caller until a connection is present. If the socket is marked nonblocking and no pending connections are present on the queue, accept returns an error as described below. The accepted socket may not be used to accept more connections. The original socket s remains open.

The argument addr is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the domain in which the communication is occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr; on return it will contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types, currently with SOCK_STREAM.

It is possible to select(2) a socket for the purposes of doing an accept by selecting it for read.

For certain protocols that require an explicit confirmation, such as ISO and DATAKIT, accept can be thought of as merely dequeuing the next connection request and not implying confirmation. Confirmation can be implied by a normal read or write on the new file descriptor, and rejection can be implied by closing the new socket.

One can obtain user connection request data without confirming the connection by issuing a recvmsg(2) call with a msg iovlen of 0 and a nonzero msg controllen, or by issuing a getsockopt(2) request. Similarly, one can provide user connection rejection information by issuing a sendmsg(2) call providing only the control information, or by calling setsockopt(2).

RETURNS VALUES

The call returns _1 on error. If it succeeds, it returns a nonnegative integer that is a descriptor for the accepted socket.

ERRORS

HISTORY

The accept function appeared in BSD 4.2.