diff options
| author | Alejandro Colomar <alx@kernel.org> | 2024-04-26 15:06:49 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2024-05-02 01:24:19 +0200 |
| commit | dcde2f70372b49ec43efc5db864c9ff585d0a2dd (patch) | |
| tree | 78b9b7425130e4a5858e4c01a524d802423879ed /man/man2/intro.2 | |
| parent | 12aca537ce78a41bbcdaf485209691e10f8002d7 (diff) | |
| download | man-pages-dcde2f70372b49ec43efc5db864c9ff585d0a2dd.tar.gz | |
man/, share/mk/: Move man*/ to man/
This is a scripted change:
$ mkdir man/;
$ mv man* man/;
$ ln -st . man/man*;
$ find share/mk/ -type f \
| xargs grep -l '^MANDIR *:=' \
| xargs sed -i '/^MANDIR *:=/s,$,/man,';
$ find share/mk/dist/ -type f \
| xargs grep -l man \
| xargs sed -i 's,man%,man/%,g';
Link: <https://lore.kernel.org/linux-man/YxcV4h+Xn7cd6+q2@pevik/T/>
Cc: Petr Vorel <pvorel@suse.cz>
Cc: Jakub Wilk <jwilk@jwilk.net>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Diffstat (limited to 'man/man2/intro.2')
| -rw-r--r-- | man/man2/intro.2 | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/man/man2/intro.2 b/man/man2/intro.2 new file mode 100644 index 0000000000..3986bb0a1e --- /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 (date) "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) |