Blame man2/intro.2

Packit 7cfc04
.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
Packit 7cfc04
.\"
Packit 7cfc04
.\" %%%LICENSE_START(VERBATIM)
Packit 7cfc04
.\" Permission is granted to make and distribute verbatim copies of this
Packit 7cfc04
.\" manual provided the copyright notice and this permission notice are
Packit 7cfc04
.\" preserved on all copies.
Packit 7cfc04
.\"
Packit 7cfc04
.\" Permission is granted to copy and distribute modified versions of this
Packit 7cfc04
.\" manual under the conditions for verbatim copying, provided that the
Packit 7cfc04
.\" entire resulting derived work is distributed under the terms of a
Packit 7cfc04
.\" permission notice identical to this one.
Packit 7cfc04
.\"
Packit 7cfc04
.\" Since the Linux kernel and libraries are constantly changing, this
Packit 7cfc04
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
Packit 7cfc04
.\" responsibility for errors or omissions, or for damages resulting from
Packit 7cfc04
.\" the use of the information contained herein.  The author(s) may not
Packit 7cfc04
.\" have taken the same level of care in the production of this manual,
Packit 7cfc04
.\" which is licensed free of charge, as they might when working
Packit 7cfc04
.\" professionally.
Packit 7cfc04
.\"
Packit 7cfc04
.\" Formatted or processed versions of this manual, if unaccompanied by
Packit 7cfc04
.\" the source, must acknowledge the copyright and authors of this work.
Packit 7cfc04
.\" %%%LICENSE_END
Packit 7cfc04
.\"
Packit 7cfc04
.\" 2007-10-23 mtk: moved the _syscallN specific material to the
Packit 7cfc04
.\"     new _syscall(2) page, and substantially enhanced and rewrote
Packit 7cfc04
.\"     the remaining material on this page.
Packit 7cfc04
.\"
Packit 7cfc04
.TH INTRO 2 2017-09-15 "Linux" "Linux Programmer's Manual"
Packit 7cfc04
.SH NAME
Packit 7cfc04
intro \- introduction to system calls
Packit 7cfc04
.SH DESCRIPTION
Packit 7cfc04
Section 2 of the manual describes the Linux system calls.
Packit 7cfc04
A system call is an entry point into the Linux kernel.
Packit 7cfc04
Usually, system calls are not invoked directly:
Packit 7cfc04
instead, most system calls have corresponding C library
Packit 7cfc04
wrapper functions which perform the steps required
Packit 7cfc04
(e.g., trapping to kernel mode) in order to invoke
Packit 7cfc04
the system call.
Packit 7cfc04
Thus, making a system call looks the same as invoking a normal
Packit 7cfc04
library function.
Packit 7cfc04
.PP
Packit 7cfc04
In many cases, the C library wrapper function does nothing more than:
Packit 7cfc04
.IP * 3
Packit 7cfc04
copying arguments and the unique system call number to the
Packit 7cfc04
registers where the kernel expects them;
Packit 7cfc04
.IP *
Packit 7cfc04
trapping to kernel mode,
Packit 7cfc04
at which point the kernel does the real work of the system call;
Packit 7cfc04
.IP *
Packit 7cfc04
setting
Packit 7cfc04
.I errno
Packit 7cfc04
if the system call returns an error number when the kernel returns the
Packit 7cfc04
CPU to user mode.
Packit 7cfc04
.PP
Packit 7cfc04
However, in a few cases, a wrapper function may do rather more than this,
Packit 7cfc04
for example, performing some preprocessing
Packit 7cfc04
of the arguments before trapping to kernel mode,
Packit 7cfc04
or postprocessing of values returned by the system call.
Packit 7cfc04
Where this is the case, the manual pages in Section 2 generally
Packit 7cfc04
try to note the details of both the (usually GNU) C library API
Packit 7cfc04
interface and the raw system call.
Packit 7cfc04
Most commonly, the main DESCRIPTION will focus on the C library interface,
Packit 7cfc04
and differences for the system call are covered in the NOTES section.
Packit 7cfc04
.PP
Packit 7cfc04
For a list of the Linux system calls, see
Packit 7cfc04
.BR syscalls (2).
Packit 7cfc04
.SH RETURN VALUE
Packit 7cfc04
On error, most system calls return a negative error number
Packit 7cfc04
(i.e., the negated value of one of the constants described in
Packit 7cfc04
.BR errno (3)).
Packit 7cfc04
The C library wrapper hides this detail from the caller: when a
Packit 7cfc04
system call returns a negative value, the wrapper copies the
Packit 7cfc04
absolute value into the
Packit 7cfc04
.I errno
Packit 7cfc04
variable, and returns \-1 as the return value of the wrapper.
Packit 7cfc04
.PP
Packit 7cfc04
The value returned by a successful system call depends on the call.
Packit 7cfc04
Many system calls return 0 on success, but some can return nonzero
Packit 7cfc04
values from a successful call.
Packit 7cfc04
The details are described in the individual manual pages.
Packit 7cfc04
.PP
Packit 7cfc04
In some cases,
Packit 7cfc04
the programmer must define a feature test macro in order to obtain
Packit 7cfc04
the declaration of a system call from the header file specified
Packit 7cfc04
in the man page SYNOPSIS section.
Packit 7cfc04
(Where required, these feature test macros must be defined before including
Packit 7cfc04
.I any
Packit 7cfc04
header files.)
Packit 7cfc04
In such cases, the required macro is described in the man page.
Packit 7cfc04
For further information on feature test macros, see
Packit 7cfc04
.BR feature_test_macros (7).
Packit 7cfc04
.SH CONFORMING TO
Packit 7cfc04
Certain terms and abbreviations are used to indicate UNIX variants
Packit 7cfc04
and standards to which calls in this section conform.
Packit 7cfc04
See
Packit 7cfc04
.BR standards (7).
Packit 7cfc04
.SH NOTES
Packit 7cfc04
.SS Calling directly
Packit 7cfc04
In most cases, it is unnecessary to invoke a system call directly,
Packit 7cfc04
but there are times when the Standard C library does not implement
Packit 7cfc04
a nice wrapper function for you.
Packit 7cfc04
In this case, the programmer must manually invoke the system call using
Packit 7cfc04
.BR syscall (2).
Packit 7cfc04
Historically, this was also possible using one of the _syscall macros
Packit 7cfc04
described in
Packit 7cfc04
.BR _syscall (2).
Packit 7cfc04
.SS Authors and copyright conditions
Packit 7cfc04
Look at the header of the manual page source for the author(s) and copyright
Packit 7cfc04
conditions.
Packit 7cfc04
Note that these can be different from page to page!
Packit 7cfc04
.SH SEE ALSO
Packit 7cfc04
.ad l
Packit 7cfc04
.nh
Packit 7cfc04
.BR _syscall (2),
Packit 7cfc04
.BR syscall (2),
Packit 7cfc04
.BR syscalls (2),
Packit 7cfc04
.BR errno (3),
Packit 7cfc04
.BR intro (3),
Packit 7cfc04
.BR capabilities (7),
Packit 7cfc04
.BR credentials (7),
Packit 7cfc04
.BR feature_test_macros (7),
Packit 7cfc04
.BR mq_overview (7),
Packit 7cfc04
.BR path_resolution (7),
Packit 7cfc04
.BR pipe (7),
Packit 7cfc04
.BR pty (7),
Packit 7cfc04
.BR sem_overview (7),
Packit 7cfc04
.BR shm_overview (7),
Packit 7cfc04
.BR signal (7),
Packit 7cfc04
.BR socket (7),
Packit 7cfc04
.BR standards (7),
Packit 7cfc04
.BR svipc (7),
Packit 7cfc04
.BR symlink (7),
Packit 7cfc04
.BR time (7)
Packit 7cfc04
.SH COLOPHON
Packit 7cfc04
This page is part of release 4.15 of the Linux
Packit 7cfc04
.I man-pages
Packit 7cfc04
project.
Packit 7cfc04
A description of the project,
Packit 7cfc04
information about reporting bugs,
Packit 7cfc04
and the latest version of this page,
Packit 7cfc04
can be found at
Packit 7cfc04
\%https://www.kernel.org/doc/man\-pages/.