Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 284 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man3/backtrace.3 b/upstream/opensuse-tumbleweed/man3/backtrace.3
new file mode 100644
index 00000000..ae970ff4
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man3/backtrace.3
@@ -0,0 +1,284 @@
+'\" t
+.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" drawing on material by Justin Pryzby <pryzbyj@justinpryzby.com>
+.\"
+.\" %%%LICENSE_START(PERMISSIVE_MISC)
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be
+.\" included in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+.\" %%%LICENSE_END
+.\"
+.\" References:
+.\"   glibc manual and source
+.TH backtrace 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+backtrace, backtrace_symbols, backtrace_symbols_fd \- support
+for application self-debugging
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <execinfo.h>
+.PP
+.BI "int backtrace(void *" buffer [. size "], int " size );
+.PP
+.BI "char **backtrace_symbols(void *const " buffer [. size "], int " size );
+.BI "void backtrace_symbols_fd(void *const " buffer [. size "], int " size ", \
+int " fd );
+.fi
+.SH DESCRIPTION
+.BR backtrace ()
+returns a backtrace for the calling program,
+in the array pointed to by
+.IR buffer .
+A backtrace is the series of currently active function calls for
+the program.
+Each item in the array pointed to by
+.I buffer
+is of type
+.IR "void\ *" ,
+and is the return address from
+the corresponding stack frame.
+The
+.I size
+argument specifies the maximum number of addresses
+that can be stored in
+.IR buffer .
+If the backtrace is larger than
+.IR size ,
+then the addresses corresponding to the
+.I size
+most recent function calls are returned;
+to obtain the complete backtrace, make sure that
+.I buffer
+and
+.I size
+are large enough.
+.PP
+Given the set of addresses returned by
+.BR backtrace ()
+in
+.IR buffer ,
+.BR backtrace_symbols ()
+translates the addresses into an array of strings that describe
+the addresses symbolically.
+The
+.I size
+argument specifies the number of addresses in
+.IR buffer .
+The symbolic representation of each address consists of the function name
+(if this can be determined), a hexadecimal offset into the function,
+and the actual return address (in hexadecimal).
+The address of the array of string pointers is returned
+as the function result of
+.BR backtrace_symbols ().
+This array is
+.BR malloc (3)ed
+by
+.BR backtrace_symbols (),
+and must be freed by the caller.
+(The strings pointed to by the array of pointers
+need not and should not be freed.)
+.PP
+.BR backtrace_symbols_fd ()
+takes the same
+.I buffer
+and
+.I size
+arguments as
+.BR backtrace_symbols (),
+but instead of returning an array of strings to the caller,
+it writes the strings, one per line, to the file descriptor
+.IR fd .
+.BR backtrace_symbols_fd ()
+does not call
+.BR malloc (3),
+and so can be employed in situations where the latter function might
+fail, but see NOTES.
+.SH RETURN VALUE
+.BR backtrace ()
+returns the number of addresses returned in
+.IR buffer ,
+which is not greater than
+.IR size .
+If the return value is less than
+.IR size ,
+then the full backtrace was stored; if it is equal to
+.IR size ,
+then it may have been truncated, in which case the addresses of the
+oldest stack frames are not returned.
+.PP
+On success,
+.BR backtrace_symbols ()
+returns a pointer to the array
+.BR malloc (3)ed
+by the call;
+on error, NULL is returned.
+.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 backtrace (),
+.BR backtrace_symbols (),
+.BR backtrace_symbols_fd ()
+T}	Thread safety	MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+GNU.
+.SH HISTORY
+glibc 2.1.
+.SH NOTES
+These functions make some assumptions about how a function's return
+address is stored on the stack.
+Note the following:
+.IP \[bu] 3
+Omission of the frame pointers (as
+implied by any of
+.BR gcc (1)'s
+nonzero optimization levels) may cause these assumptions to be
+violated.
+.IP \[bu]
+Inlined functions do not have stack frames.
+.IP \[bu]
+Tail-call optimization causes one stack frame to replace another.
+.IP \[bu]
+.BR backtrace ()
+and
+.BR backtrace_symbols_fd ()
+don't call
+.BR malloc ()
+explicitly, but they are part of
+.IR libgcc ,
+which gets loaded dynamically when first used.
+Dynamic loading usually triggers a call to
+.BR malloc (3).
+If you need certain calls to these two functions to not allocate memory
+(in signal handlers, for example), you need to make sure
+.I libgcc
+is loaded beforehand.
+.PP
+The symbol names may be unavailable without the use of special linker
+options.
+For systems using the GNU linker, it is necessary to use the
+.I \-rdynamic
+linker option.
+Note that names of "static" functions are not exposed,
+and won't be available in the backtrace.
+.SH EXAMPLES
+The program below demonstrates the use of
+.BR backtrace ()
+and
+.BR backtrace_symbols ().
+The following shell session shows what we might see when running the
+program:
+.PP
+.in +4n
+.EX
+.RB "$" " cc \-rdynamic prog.c \-o prog"
+.RB "$" " ./prog 3"
+backtrace() returned 8 addresses
+\&./prog(myfunc3+0x5c) [0x80487f0]
+\&./prog [0x8048871]
+\&./prog(myfunc+0x21) [0x8048894]
+\&./prog(myfunc+0x1a) [0x804888d]
+\&./prog(myfunc+0x1a) [0x804888d]
+\&./prog(main+0x65) [0x80488fb]
+\&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
+\&./prog [0x8048711]
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (backtrace.c)
+.EX
+#include <execinfo.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+\&
+#define BT_BUF_SIZE 100
+\&
+void
+myfunc3(void)
+{
+    int nptrs;
+    void *buffer[BT_BUF_SIZE];
+    char **strings;
+\&
+    nptrs = backtrace(buffer, BT_BUF_SIZE);
+    printf("backtrace() returned %d addresses\en", nptrs);
+\&
+    /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
+       would produce similar output to the following: */
+\&
+    strings = backtrace_symbols(buffer, nptrs);
+    if (strings == NULL) {
+        perror("backtrace_symbols");
+        exit(EXIT_FAILURE);
+    }
+\&
+    for (size_t j = 0; j < nptrs; j++)
+        printf("%s\en", strings[j]);
+\&
+    free(strings);
+}
+\&
+static void   /* "static" means don\[aq]t export the symbol... */
+myfunc2(void)
+{
+    myfunc3();
+}
+\&
+void
+myfunc(int ncalls)
+{
+    if (ncalls > 1)
+        myfunc(ncalls \- 1);
+    else
+        myfunc2();
+}
+\&
+int
+main(int argc, char *argv[])
+{
+    if (argc != 2) {
+        fprintf(stderr, "%s num\-calls\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    myfunc(atoi(argv[1]));
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR addr2line (1),
+.BR gcc (1),
+.BR gdb (1),
+.BR ld (1),
+.BR dlopen (3),
+.BR malloc (3)