Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 115 insertions, 0 deletions

diff --git a/man/man2/intro.2 b/man/man2/intro.2
new file mode 100644
index 0000000..f9455ee
--- /dev/null
+++ b/man/man2/intro.2
@@ -0,0 +1,115 @@
+.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 2007-10-23 mtk: moved the _syscallN specific material to the
+.\"     new _syscall(2) page, and substantially enhanced and rewrote
+.\"     the remaining material on this page.
+.\"
+.TH intro 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+intro \- introduction to system calls
+.SH DESCRIPTION
+Section 2 of the manual describes the Linux system calls.
+A system call is an entry point into the Linux kernel.
+Usually, system calls are not invoked directly:
+instead, most system calls have corresponding C library
+wrapper functions which perform the steps required
+(e.g., trapping to kernel mode) in order to invoke
+the system call.
+Thus, making a system call looks the same as invoking a normal
+library function.
+.P
+In many cases, the C library wrapper function does nothing more than:
+.IP \[bu] 3
+copying arguments and the unique system call number to the
+registers where the kernel expects them;
+.IP \[bu]
+trapping to kernel mode,
+at which point the kernel does the real work of the system call;
+.IP \[bu]
+setting
+.I errno
+if the system call returns an error number when the kernel returns the
+CPU to user mode.
+.P
+However, in a few cases, a wrapper function may do rather more than this,
+for example, performing some preprocessing
+of the arguments before trapping to kernel mode,
+or postprocessing of values returned by the system call.
+Where this is the case, the manual pages in Section 2 generally
+try to note the details of both the (usually GNU) C library API
+interface and the raw system call.
+Most commonly, the main DESCRIPTION will focus on the C library interface,
+and differences for the system call are covered in the NOTES section.
+.P
+For a list of the Linux system calls, see
+.BR syscalls (2).
+.SH RETURN VALUE
+On error, most system calls return a negative error number
+(i.e., the negated value of one of the constants described in
+.BR errno (3)).
+The C library wrapper hides this detail from the caller: when a
+system call returns a negative value, the wrapper copies the
+absolute value into the
+.I errno
+variable, and returns \-1 as the return value of the wrapper.
+.P
+The value returned by a successful system call depends on the call.
+Many system calls return 0 on success, but some can return nonzero
+values from a successful call.
+The details are described in the individual manual pages.
+.P
+In some cases,
+the programmer must define a feature test macro in order to obtain
+the declaration of a system call from the header file specified
+in the man page SYNOPSIS section.
+(Where required, these feature test macros must be defined before including
+.I any
+header files.)
+In such cases, the required macro is described in the man page.
+For further information on feature test macros, see
+.BR feature_test_macros (7).
+.SH STANDARDS
+Certain terms and abbreviations are used to indicate UNIX variants
+and standards to which calls in this section conform.
+See
+.BR standards (7).
+.SH NOTES
+.SS 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 wrapper function for you.
+In this case, the programmer must manually invoke the system call using
+.BR syscall (2).
+Historically, this was also possible using one of the _syscall macros
+described in
+.BR _syscall (2).
+.SS Authors and copyright conditions
+Look at the header of the manual page source for the author(s) and copyright
+conditions.
+Note that these can be different from page to page!
+.SH SEE ALSO
+.ad l
+.nh
+.BR _syscall (2),
+.BR syscall (2),
+.BR syscalls (2),
+.BR errno (3),
+.BR intro (3),
+.BR capabilities (7),
+.BR credentials (7),
+.BR feature_test_macros (7),
+.BR mq_overview (7),
+.BR path_resolution (7),
+.BR pipe (7),
+.BR pty (7),
+.BR sem_overview (7),
+.BR shm_overview (7),
+.BR signal (7),
+.BR socket (7),
+.BR standards (7),
+.BR symlink (7),
+.BR system_data_types (7),
+.BR sysvipc (7),
+.BR time (7)