diff options
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 000000000..3986bb0a1 --- /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) |