man2 - System calls

INTRO(2) Linux Programmer's Manual INTRO(2)

intro, _syscall - Introduction to system calls

This chapter describes the Linux system calls. For a list of the 164 syscalls present in Linux 2.0, see syscalls(2).

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.

#include <linux/unistd.h>

A _syscall macro

desired system call

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,type1,arg1,type2,arg2,...)

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

typeN is the Nth argument's type

argN is the name of the Nth 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.


#include <stdio.h>
#include <errno.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 you 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 = %lds\nLoad: 1 min %lu / 5 min %lu / 15 min %lu\n"

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

                "Memory in buffers = %lu\nSwap: total %lu / free %lu\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);
}

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

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, e.g., -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. For the error codes, see errno(3).

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 like structs).

The preferred way to invoke system calls that glibc does not know about yet, is via syscall(2).

Certain codes are used to indicate Unix variants and standards to which calls in the section conform. These are:

System V Release 4 Unix, as described in the "Programmer's Reference Manual: Operating System API (Intel processors)" (Prentice-Hall 1992, ISBN 0-13-951294-2)
System V Interface Definition, as described in "The System V Interface Definition, Fourth Edition".
IEEE 1003.1-1990 part 1, aka ISO/IEC 9945-1:1990s, aka "IEEE Portable Operating System Interface for Computing Environments", as elucidated in Donald Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, Inc., 1991, ISBN 0-937175-73-0.
IEEE Std 1003.1b-1993 (POSIX.1b standard) describing real-time facilities for portable operating systems, aka ISO/IEC 9945-1:1996, as elucidated in "Programming for the real world - POSIX.4" by Bill O. Gallmeister (O'Reilly & Associates, Inc. ISBN 1-56592-074-0).
Single Unix Specification. (Developed by X/Open and The Open Group. See also http://www.UNIX-systems.org/version2/ .)
4.3BSD/4.4BSD
The 4.3 and 4.4 distributions of Berkeley Unix. 4.4BSD was upward-compatible from 4.3.
Version 7, the ancestral Unix from Bell Labs.

/usr/include/linux/unistd.h

syscall(2), errno(3)

1996-05-22 Linux 1.2.13

Pages:

man_EXIT(2) _Exit man_EXIT(2) _exit manLLSEEK(2) _llseek manSELECT(2) _newselect manSYSCTL(2) _sysctl manACCEPT(2) accept manACCESS(2) access manACCT(2) acct manADJTIMEX(2) adjtimex manUNIMPLEMENTED(2) afs_syscall manALARM(2) alarm manALLOC_HUGEPAGES(2) alloc_hugepages manARCH_PRCTL(2) arch_prctl manBDFLUSH(2) bdflush manBIND(2) bind manUNIMPLEMENTED(2) break manBRK(2) brk manCACHEFLUSH(2) cacheflush manCAPGET(2) capget manCAPGET(2) capset manCHDIR(2) chdir manCHMOD(2) chmod manCHOWN(2) chown manCHROOT(2) chroot manCLONE(2) clone manCLOSE(2) close manCONNECT(2) connect manOPEN(2) creat manDUP(2) dup manDUP(2) dup2 manEPOLL_CREATE(2) epoll_create manEPOLL_CTL(2) epoll_ctl manEPOLL_WAIT(2) epoll_wait manEXECVE(2) execve man_EXIT(2) exit manEXIT_GROUP(2) exit_group manCHDIR(2) fchdir manCHMOD(2) fchmod manCHOWN(2) fchown manFCNTL(2) fcntl manFDATASYNC(2) fdatasync manGETXATTR(2) fgetxattr manLISTXATTR(2) flistxattr manFLOCK(2) flock manFORK(2) fork manALLOC_HUGEPAGES(2) free_hugepages manREMOVEXATTR(2) fremovexattr manSETXATTR(2) fsetxattr manSTAT(2) fstat manSTATFS(2) fstatfs manSTATVFS(2) fstatvfs manFSYNC(2) fsync manTRUNCATE(2) ftruncate manFUTEX(2) futex manGET_THREAD_AREA(2) get_thread_area manGETCONTEXT(2) getcontext manGETDENTS(2) getdents manGETDOMAINNAME(2) getdomainname manGETDTABLESIZE(2) getdtablesize manGETGID(2) getegid manGETUID(2) geteuid manGETGID(2) getgid manGETGROUPS(2) getgroups manGETHOSTID(2) gethostid manGETHOSTNAME(2) gethostname manGETITIMER(2) getitimer manGETPAGESIZE(2) getpagesize manGETPEERNAME(2) getpeername manSETPGID(2) getpgid manSETPGID(2) getpgrp manGETPID(2) getpid manUNIMPLEMENTED(2) getpmsg manGETPID(2) getppid manGETPRIORITY(2) getpriority manGETRESUID(2) getresgid manGETRESUID(2) getresuid manGETRLIMIT(2) getrlimit manGETRUSAGE(2) getrusage manGETSID(2) getsid manGETSOCKNAME(2) getsockname manGETSOCKOPT(2) getsockopt manGETTID(2) gettid manGETTIMEOFDAY(2) gettimeofday manGETUID(2) getuid manGETXATTR(2) getxattr manUNIMPLEMENTED(2) gtty manIDLE(2) idle manOUTB(2) inb manOUTB(2) inb_p manOUTB(2) inl manOUTB(2) inl_p manOUTB(2) insb manOUTB(2) insl manOUTB(2) insw manINTRO(2) intro manOUTB(2) inw manOUTB(2) inw_p manIO_CANCEL(2) io_cancel manIO_DESTROY(2) io_destroy manIO_GETEVENTS(2) io_getevents manIO_SETUP(2) io_setup manIO_SUBMIT(2) io_submit manIOCTL(2) ioctl manIOCTL_LIST(2) ioctl_list manIOPERN(2) ioperm manIOPL(2) iopl manIPC(2) ipc manKILL(2) kill manKILLPG(2) killpg manCHOWN(2) lchown manGETXATTR(2) lgetxattr manLINK(2) link manLISTEN(2) listen manLISTXATTR(2) listxattr manLISTXATTR(2) llistxattr manLLSEEK(2) llseek manUNIMPLEMENTED(2) lock manLOOKUP_DCOOKIE(2) lookup_dcookie manREMOVEXATTR(2) lremovexattr manLSEEK(2) lseek manSETXATTR(2) lsetxattr manSTAT(2) lstat manMADVISE(2) madvise manMINCORE(2) mincore manMKDIR(2) mkdir manMKNOD(2) mknod manMLOCK(2) mlock manMLOCK(2) mlockall manMMAP(2) mmap manMMAP2(2) mmap2 manMODIFY_LDT(2) modify_ldt manMOUNT(2) mount manMPROTECT(2) mprotect manUNIMPLEMENTED(2) mpx manMREMAP(2) mremap manMSGCTL(2) msgctl manMSGGET(2) msgget manMSGOP(2) msgop manMSGOP(2) msgrcv manMSGOP(2) msgsnd manMSYNC(2) msync manMLOCK(2) munlock manMLOCK(2) munlockall manMMAP(2) munmap manNANOSLEEP(2) nanosleep manNFSSERVCTL(2) nfsservctl manNICE(2) nice manOBSOLETE(2) obsolete manOBSOLETE(2) oldfstat manOBSOLETE(2) oldlstat manOBSOLETE(2) oldolduname manOBSOLETE(2) oldstat manOBSOLETE(2) olduname manOPEN(2) open manOUTB(2) outb manOUTB(2) outb_p manOUTB(2) outl manOUTB(2) outl_p manOUTB(2) outsb manOUTB(2) outsl manOUTB(2) outsw manOUTB(2) outw manOUTB(2) outw_p manPATH_RESOLUTION(2) path_resolution manPAUSE(2) pause manPCICONFIG_READ(2) pciconfig_iobase manPCICONFIG_READ(2) pciconfig_read manPCICONFIG_READ(2) pciconfig_write manPERSONALITY(2) personality manPIPE(2) pipe manPIVOT_ROOT(2) pivot_root manPOLL(2) poll manPOSIX_FADVISE(2) posix_fadvise manPRCTL(2) prctl manPREAD(2) pread manUNIMPLEMENTED(2) prof manSELECT(2) pselect manPTRACE(2) ptrace manUNIMPLEMENTED(2) putpmsg manPREAD(2) pwrite manQUOTACTL(2) quotactl manREAD(2) read manREADAHEAD(2) readahead manREADDIR(2) readdir manREADLINK(2) readlink manREADV(2) readv manREBOOT(2) reboot manRECV(2) recv manRECV(2) recvfrom manRECV(2) recvmsg manREMAP_FILE_PAGES(2) remap_file_pages manREMOVEXATTR(2) removexattr manRENAME(2) rename manRMDIR(2) rmdir manBRK(2) sbrk manGET_PRIORITY_MAX(2) sched_get_priority_max manGET_PRIORITY_MAX(2) sched_get_priority_min manSCHED_SETAFFINITY(2) sched_getaffinity manSCHED_SETPARAM(2) sched_getparam manSETSCHEDULER(2) sched_getscheduler manRR_GET_INTERVAL(2) sched_rr_get_interval manSCHED_SETAFFINITY(2) sched_setaffinity manSCHED_SETPARAM(2) sched_setparam manSETSCHEDULER(2) sched_setscheduler manSCHED_YIELD(2) sched_yield manUNIMPLEMENTED(2) security manSELECT(2) select manSELECT_TUT(2) select_tut manSEMCTL(2) semctl manSEMGET(2) semget manSEMOP(2) semop manSEMOP(2) semtimedop manSEND(2) send manSENDFILE(2) sendfile manSEND(2) sendmsg manSEND(2) sendto manSET_THREAD_AREA(2) set_thread_area manSET_TID_ADDRESS(2) set_tid_address manGETCONTEXT(2) setcontext manGETDOMAINNAME(2) setdomainname manSETEGID(2) setegid manSETEGID(2) seteuid manSETFSGID(2) setfsgid manSETFSUID(2) setfsuid manSETGID(2) setgid manGETGROUPS(2) setgroups manGETHOSTID(2) sethostid manGETHOSTNAME(2) sethostname manGETITIMER(2) setitimer manSETPGID(2) setpgid manSETPGID(2) setpgrp manGETPRIORITY(2) setpriority manSETREUID(2) setregid manSETRESUID(2) setresgid manSETRESUID(2) setresuid manSETREUID(2) setreuid manGETRLIMIT(2) setrlimit manSETSID(2) setsid manGETSOCKOPT(2) setsockopt manGETTIMEOFDAY(2) settimeofday manSETUID(2) setuid manSETUP(2) setup manSETXATTR(2) setxattr manSIGNAL(2) sgetmask manSHMOP(2) shmat manSHMCTL(2) shmctl manSHMOP(2) shmdt manSHMGET(2) shmget manSHMOP(2) shmop manSHUTDOWN(2) shutdown manSIGACTION(2) sigaction manSIGALTSTACK(2) sigaltstack manSIGBLOCK(2) sigblock manSIGBLOCK(2) siggetmask manSIGBLOCK(2) sigmask manSIGNAL(2) signal manSIGPAUSE(2) sigpause manSIGPENDING(2) sigpending manSIGPROCMASK(2) sigprocmask manSIGQUEUE(2) sigqueue manSIGRETURN(2) sigreturn manSIGBLOCK(2) sigsetmask manSIGSUSPEND(2) sigsuspend manSIGWAITINFO(2) sigtimedwait manSIGVEC(2) sigvec manSIGWAITINFO(2) sigwaitinfo manSOCKET(2) socket manIPC(2) socketcall manSOCKETPAIR(2) socketpair manSIGNAL(2) ssetmask manSTAT(2) stat manSTATFS(2) statfs manSTATVFS(2) statvfs manSTIME(2) stime manUNIMPLEMENTED(2) stty manSWAPON(2) swapoff manSWAPON(2) swapon manSYMLINK(2) symlink manSYNC(2) sync manSYSCALL(2) syscall manSYSCALLS(2) syscalls manSYSCTL(2) sysctl manSYSFS(2) sysfs manSYSINFO(2) sysinfo manSYSLOG(2) syslog manTKILL(2) tgkill manTIME(2) time manTIMES(2) times manTKILL(2) tkill manTRUNCATE(2) truncate manUMASK(2) umask manMOUNT(2) umount manMOUNT(2) umount2 manUNAME(2) uname manUNDOCUMENTED(2) undocumented manUNIMPLEMENTED(2) unimplemented manUNLINK(2) unlink manUSELIB(2) uselib manUSTAT(2) ustat manUTIME(2) utime manUTIME(2) utimes manVFORK(2) vfork manVHANGUP(2) vhangup manVM86(2) vm86 manWAIT(2) wait manWAIT4(2) wait3 manWAIT4(2) wait4 manWAIT(2) waitid manWAIT(2) waitpid manWRITE(2) write manREADV(2) writev

Different Versions of this Section: