Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 315 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man2/vfork.2 b/upstream/debian-bookworm/man2/vfork.2
new file mode 100644
index 00000000..0c3ad6c0
--- /dev/null
+++ b/upstream/debian-bookworm/man2/vfork.2
@@ -0,0 +1,315 @@
+.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl), 1 Nov 1999
+.\" and Copyright 2006, 2012, 2017 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 1999-11-10: Merged text taken from the page contributed by
+.\" Reed H. Petty (rhp@draper.net)
+.\"
+.TH vfork 2 2023-02-05 "Linux man-pages 6.03"
+.SH NAME
+vfork \- create a child process and block parent
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.PP
+.B pid_t vfork(void);
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR vfork ():
+.nf
+    Since glibc 2.12:
+        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
+            || /* Since glibc 2.19: */ _DEFAULT_SOURCE
+            || /* glibc <= 2.19: */ _BSD_SOURCE
+    Before glibc 2.12:
+        _BSD_SOURCE || _XOPEN_SOURCE >= 500
+.\"     || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+.fi
+.SH DESCRIPTION
+.SS Standard description
+(From POSIX.1)
+The
+.BR vfork ()
+function has the same effect as
+.BR fork (2),
+except that the behavior is undefined if the process created by
+.BR vfork ()
+either modifies any data other than a variable of type
+.I pid_t
+used to store the return value from
+.BR vfork (),
+or returns from the function in which
+.BR vfork ()
+was called, or calls any other function before successfully calling
+.BR _exit (2)
+or one of the
+.BR exec (3)
+family of functions.
+.SS Linux description
+.BR vfork (),
+just like
+.BR fork (2),
+creates a child process of the calling process.
+For details and return value and errors, see
+.BR fork (2).
+.PP
+.BR vfork ()
+is a special case of
+.BR clone (2).
+It is used to create new processes without copying the page tables of
+the parent process.
+It may be useful in performance-sensitive applications
+where a child is created which then immediately issues an
+.BR execve (2).
+.PP
+.BR vfork ()
+differs from
+.BR fork (2)
+in that the calling thread is suspended until the child terminates
+(either normally,
+by calling
+.BR _exit (2),
+or abnormally, after delivery of a fatal signal),
+or it makes a call to
+.BR execve (2).
+Until that point, the child shares all memory with its parent,
+including the stack.
+The child must not return from the current function or call
+.BR exit (3)
+(which would have the effect of calling exit handlers
+established by the parent process and flushing the parent's
+.BR stdio (3)
+buffers), but may call
+.BR _exit (2).
+.PP
+As with
+.BR fork (2),
+the child process created by
+.BR vfork ()
+inherits copies of various of the caller's process attributes
+(e.g., file descriptors, signal dispositions, and current working directory);
+the
+.BR vfork ()
+call differs only in the treatment of the virtual address space,
+as described above.
+.PP
+Signals sent to the parent
+arrive after the child releases the parent's memory
+(i.e., after the child terminates
+or calls
+.BR execve (2)).
+.SS Historic description
+Under Linux,
+.BR fork (2)
+is implemented using copy-on-write pages, so the only penalty incurred by
+.BR fork (2)
+is the time and memory required to duplicate the parent's page tables,
+and to create a unique task structure for the child.
+However, in the bad old days a
+.BR fork (2)
+would require making a complete copy of the caller's data space,
+often needlessly, since usually immediately afterward an
+.BR exec (3)
+is done.
+Thus, for greater efficiency, BSD introduced the
+.BR vfork ()
+system call, which did not fully copy the address space of
+the parent process, but borrowed the parent's memory and thread
+of control until a call to
+.BR execve (2)
+or an exit occurred.
+The parent process was suspended while the
+child was using its resources.
+The use of
+.BR vfork ()
+was tricky: for example, not modifying data
+in the parent process depended on knowing which variables were
+held in a register.
+.SH STANDARDS
+4.3BSD; POSIX.1-2001 (but marked OBSOLETE).
+POSIX.1-2008 removes the specification of
+.BR vfork ().
+.PP
+The requirements put on
+.BR vfork ()
+by the standards are weaker than those put on
+.BR fork (2),
+so an implementation where the two are synonymous is compliant.
+In particular, the programmer cannot rely on the parent
+remaining blocked until the child either terminates or calls
+.BR execve (2),
+and cannot rely on any specific behavior with respect to shared memory.
+.\" In AIXv3.1 vfork is equivalent to fork.
+.SH NOTES
+Some consider the semantics of
+.BR vfork ()
+to be an architectural blemish, and the 4.2BSD man page stated:
+"This system call will be eliminated when proper system sharing mechanisms
+are implemented.
+Users should not depend on the memory sharing semantics of
+.BR vfork ()
+as it will, in that case, be made synonymous to
+.BR fork (2).\c
+"
+However, even though modern memory management hardware
+has decreased the performance difference between
+.BR fork (2)
+and
+.BR vfork (),
+there are various reasons why Linux and other systems have retained
+.BR vfork ():
+.IP \[bu] 3
+Some performance-critical applications require the small performance
+advantage conferred by
+.BR vfork ().
+.IP \[bu]
+.BR vfork ()
+can be implemented on systems that lack a memory-management unit (MMU), but
+.BR fork (2)
+can't be implemented on such systems.
+(POSIX.1-2008 removed
+.BR vfork ()
+from the standard; the POSIX rationale for the
+.BR posix_spawn (3)
+function notes that that function,
+which provides functionality equivalent to
+.BR fork (2)+\c
+.BR exec (3),
+is designed to be implementable on systems that lack an MMU.)
+.\" http://stackoverflow.com/questions/4259629/what-is-the-difference-between-fork-and-vfork
+.\" http://developers.sun.com/solaris/articles/subprocess/subprocess.html
+.\" http://mailman.uclinux.org/pipermail/uclinux-dev/2009-April/000684.html
+.\"
+.IP \[bu]
+On systems where memory is constrained,
+.BR vfork ()
+avoids the need to temporarily commit memory (see the description of
+.I /proc/sys/vm/overcommit_memory
+in
+.BR proc (5))
+in order to execute a new program.
+(This can be especially beneficial where a large parent process wishes
+to execute a small helper program in a child process.)
+By contrast, using
+.BR fork (2)
+in this scenario requires either committing an amount of memory equal
+to the size of the parent process (if strict overcommitting is in force)
+or overcommitting memory with the risk that a process is terminated
+by the out-of-memory (OOM) killer.
+.\"
+.SS Caveats
+The child process should take care not to modify the memory in unintended ways,
+since such changes will be seen by the parent process once
+the child terminates or executes another program.
+In this regard, signal handlers can be especially problematic:
+if a signal handler that is invoked in the child of
+.BR vfork ()
+changes memory, those changes may result in an inconsistent process state
+from the perspective of the parent process
+(e.g., memory changes would be visible in the parent,
+but changes to the state of open file descriptors would not be visible).
+.PP
+When
+.BR vfork ()
+is called in a multithreaded process,
+only the calling thread is suspended until the child terminates
+or executes a new program.
+This means that the child is sharing an address space with other running code.
+This can be dangerous if another thread in the parent process
+changes credentials (using
+.BR setuid (2)
+or similar),
+since there are now two processes with different privilege levels
+running in the same address space.
+As an example of the dangers,
+suppose that a multithreaded program running as root creates a child using
+.BR vfork ().
+After the
+.BR vfork (),
+a thread in the parent process drops the process to an unprivileged user
+in order to run some untrusted code
+(e.g., perhaps via plug-in opened with
+.BR dlopen (3)).
+In this case, attacks are possible where the parent process uses
+.BR mmap (2)
+to map in code that will be executed by the privileged child process.
+.\"
+.SS Linux notes
+Fork handlers established using
+.BR pthread_atfork (3)
+are not called when a multithreaded program employing
+the NPTL threading library calls
+.BR vfork ().
+Fork handlers are called in this case in a program using the
+LinuxThreads threading library.
+(See
+.BR pthreads (7)
+for a description of Linux threading libraries.)
+.PP
+A call to
+.BR vfork ()
+is equivalent to calling
+.BR clone (2)
+with
+.I flags
+specified as:
+.PP
+.in +4n
+.EX
+ CLONE_VM | CLONE_VFORK | SIGCHLD
+.EE
+.in
+.SS History
+The
+.BR vfork ()
+system call appeared in 3.0BSD.
+.\" In the release notes for 4.2BSD Sam Leffler wrote: `vfork: Is still
+.\" present, but definitely on its way out'.
+In 4.4BSD it was made synonymous to
+.BR fork (2)
+but NetBSD introduced it again;
+see
+.UR http://www.netbsd.org\:/Documentation\:/kernel\:/vfork.html
+.UE .
+In Linux, it has been equivalent to
+.BR fork (2)
+until Linux 2.2.0-pre6 or so.
+Since Linux 2.2.0-pre9 (on i386, somewhat later on
+other architectures) it is an independent system call.
+Support was added in glibc 2.0.112.
+.SH BUGS
+Details of the signal handling are obscure and differ between systems.
+The BSD man page states:
+"To avoid a possible deadlock situation, processes that are children
+in the middle of a
+.BR vfork ()
+are never sent
+.B SIGTTOU
+or
+.B SIGTTIN
+signals; rather, output or
+.IR ioctl s
+are allowed and input attempts result in an end-of-file indication."
+.\"
+.\" As far as I can tell, the following is not true in Linux 2.6.19:
+.\" Currently (Linux 2.3.25),
+.\" .BR strace (1)
+.\" cannot follow
+.\" .BR vfork ()
+.\" and requires a kernel patch.
+.SH SEE ALSO
+.BR clone (2),
+.BR execve (2),
+.BR _exit (2),
+.BR fork (2),
+.BR unshare (2),
+.BR wait (2)