Adding upstream version 6.05.01.upstream/6.05.01

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

1 files changed, 270 insertions, 0 deletions

diff --git a/man3/system.3 b/man3/system.3
new file mode 100644
index 0000000..8615623
--- /dev/null
+++ b/man3/system.3
@@ -0,0 +1,270 @@
+'\" t
+.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
+.\" and Copyright (c) 2014 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Sat Jul 24 17:51:15 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
+.\" Modified 14 May 2001, 23 Sep 2001 by aeb
+.\" 2004-12-20, mtk
+.\"
+.TH system 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+system \- execute a shell command
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.PP
+.BI "int system(const char *" "command" );
+.fi
+.SH DESCRIPTION
+The
+.BR system ()
+library function behaves as if it used
+.BR fork (2)
+to create a child process that executed the shell command specified in
+.I command
+using
+.BR execl (3)
+as follows:
+.PP
+.in +4n
+.EX
+execl("/bin/sh", "sh", "\-c", command, (char *) NULL);
+.EE
+.in
+.PP
+.BR system ()
+returns after the command has been completed.
+.PP
+During execution of the command,
+.B SIGCHLD
+will be blocked, and
+.B SIGINT
+and
+.B SIGQUIT
+will be ignored, in the process that calls
+.BR system ().
+(These signals will be handled according to their defaults inside
+the child process that executes
+.IR command .)
+.PP
+If
+.I command
+is NULL, then
+.BR system ()
+returns a status indicating whether a shell is available on the system.
+.SH RETURN VALUE
+The return value of
+.BR system ()
+is one of the following:
+.IP \[bu] 3
+If
+.I command
+is NULL, then a nonzero value if a shell is available,
+or 0 if no shell is available.
+.IP \[bu]
+If a child process could not be created,
+or its status could not be retrieved,
+the return value is \-1 and
+.I errno
+is set to indicate the error.
+.IP \[bu]
+If a shell could not be executed in the child process,
+then the return value is as though the child shell terminated by calling
+.BR _exit (2)
+with the status 127.
+.IP \[bu]
+If all system calls succeed,
+then the return value is the termination status of the child shell
+used to execute
+.IR command .
+(The termination status of a shell is the termination status of
+the last command it executes.)
+.PP
+In the last two cases,
+the return value is a "wait status" that can be examined using
+the macros described in
+.BR waitpid (2).
+(i.e.,
+.BR WIFEXITED (),
+.BR WEXITSTATUS (),
+and so on).
+.PP
+.BR system ()
+does not affect the wait status of any other children.
+.SH ERRORS
+.BR system ()
+can fail with any of the same errors as
+.BR fork (2).
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR system ()
+T}	Thread safety	MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, C89.
+.SH NOTES
+.BR system ()
+provides simplicity and convenience:
+it handles all of the details of calling
+.BR fork (2),
+.BR execl (3),
+and
+.BR waitpid (2),
+as well as the necessary manipulations of signals;
+in addition,
+the shell performs the usual substitutions and I/O redirections for
+.IR command .
+The main cost of
+.BR system ()
+is inefficiency:
+additional system calls are required to create the process that
+runs the shell and to execute the shell.
+.PP
+If the
+.B _XOPEN_SOURCE
+feature test macro is defined
+(before including
+.I any
+header files),
+then the macros described in
+.BR waitpid (2)
+.RB ( WEXITSTATUS (),
+etc.) are made available when including
+.IR <stdlib.h> .
+.PP
+As mentioned,
+.BR system ()
+ignores
+.B SIGINT
+and
+.BR SIGQUIT .
+This may make programs that call it
+from a loop uninterruptible, unless they take care themselves
+to check the exit status of the child.
+For example:
+.PP
+.in +4n
+.EX
+while (something) {
+    int ret = system("foo");
+\&
+    if (WIFSIGNALED(ret) &&
+        (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT))
+            break;
+}
+.EE
+.in
+.PP
+According to POSIX.1, it is unspecified whether handlers registered using
+.BR pthread_atfork (3)
+are called during the execution of
+.BR system ().
+In the glibc implementation, such handlers are not called.
+.PP
+Before glibc 2.1.3, the check for the availability of
+.I /bin/sh
+was not actually performed if
+.I command
+was NULL; instead it was always assumed to be available, and
+.BR system ()
+always returned 1 in this case.
+Since glibc 2.1.3, this check is performed because, even though
+POSIX.1-2001 requires a conforming implementation to provide
+a shell, that shell may not be available or executable if
+the calling program has previously called
+.BR chroot (2)
+(which is not specified by POSIX.1-2001).
+.PP
+It is possible for the shell command to terminate with a status of 127,
+which yields a
+.BR system ()
+return value that is indistinguishable from the case
+where a shell could not be executed in the child process.
+.\"
+.SS Caveats
+Do not use
+.BR system ()
+from a privileged program
+(a set-user-ID or set-group-ID program, or a program with capabilities)
+because strange values for some environment variables
+might be used to subvert system integrity.
+For example,
+.B PATH
+could be manipulated so that an arbitrary program
+is executed with privilege.
+Use the
+.BR exec (3)
+family of functions instead, but not
+.BR execlp (3)
+or
+.BR execvp (3)
+(which also use the
+.B PATH
+environment variable to search for an executable).
+.PP
+.BR system ()
+will not, in fact, work properly from programs with set-user-ID or
+set-group-ID privileges on systems on which
+.I /bin/sh
+is bash version 2: as a security measure, bash 2 drops privileges on startup.
+(Debian uses a different shell,
+.BR dash (1),
+which does not do this when invoked as
+.BR sh .)
+.PP
+Any user input that is employed as part of
+.I command
+should be
+.I carefully
+sanitized, to ensure that unexpected shell commands or command options
+are not executed.
+Such risks are especially grave when using
+.BR system ()
+from a privileged program.
+.SH BUGS
+.\" [BUG 211029](https://bugzilla.kernel.org/show_bug.cgi?id=211029)
+.\" [glibc bug](https://sourceware.org/bugzilla/show_bug.cgi?id=27143)
+.\" [POSIX bug](https://www.austingroupbugs.net/view.php?id=1440)
+If the command name starts with a hyphen,
+.BR sh (1)
+interprets the command name as an option,
+and the behavior is undefined.
+(See the
+.B \-c
+option to
+.BR sh (1).)
+To work around this problem,
+prepend the command with a space as in the following call:
+.PP
+.in +4n
+.EX
+    system(" \-unfortunate\-command\-name");
+.EE
+.in
+.SH SEE ALSO
+.BR sh (1),
+.BR execve (2),
+.BR fork (2),
+.BR sigaction (2),
+.BR sigprocmask (2),
+.BR wait (2),
+.BR exec (3),
+.BR signal (7)