mirror of https://github.com/mkerrisk/man-pages
getunwind.2: Much rewriting
Some text taken from arch/ia64/kernel/unwind.c. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk
parent
4288c61864
commit
fe828902eb
|
|
@ -1,5 +1,6 @@
|
|||
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
||||
.\" Written by Marcela Maslanova <mmaslano@redhat.com>
|
||||
.\" and Copyright 2013, Michael kerrisk <mtk.manpages@gmail.com>
|
||||
.\"
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
|
|
@ -22,7 +23,7 @@
|
|||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\"
|
||||
.\"
|
||||
.TH GETUNWIND 2 "29 August 2006" Linux "Linux System Calls"
|
||||
.TH GETUNWIND 2 2013-02-13" Linux "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
getunwind \- copy the unwind data to caller's buffer
|
||||
|
||||
|
|
@ -31,23 +32,39 @@ getunwind \- copy the unwind data to caller's buffer
|
|||
.B #include <syscall.h>
|
||||
.B #include <linux/unwind.h>
|
||||
.sp
|
||||
.BI "long getunwind (void " *buf ", size_t " buf_size );
|
||||
.BI "long getunwind(void " *buf ", size_t " buf_size );
|
||||
.fi
|
||||
|
||||
.IR Note :
|
||||
There is no glibc wrapper for this system call; see NOTES.
|
||||
.SH DESCRIPTION
|
||||
.I Note: this function is obsolete.
|
||||
|
||||
The
|
||||
.B sys_getunwind
|
||||
function returns size of unwind table, which describes gate page (kernel code that
|
||||
IA-64-specific
|
||||
.BR getunwind ()
|
||||
system call copies the kernel's call frame
|
||||
unwind data into the buffer pointed to by
|
||||
.I buf
|
||||
and returns the size of the unwind data;
|
||||
this data describes the gate page (kernel code that
|
||||
is mapped into user space).
|
||||
|
||||
The unwind data is copied to the buffer \fIbuf\fR, which has size \fIbuf_size\fR.
|
||||
The data is copied
|
||||
only if \fIbuf_size\fR is greater than or equal to the size of the
|
||||
unwind data and \fIbuf\fR is not NULL.
|
||||
The system call returns the size of the unwind data in both cases.
|
||||
The size of the buffer
|
||||
.I buf
|
||||
is specified in
|
||||
.IR buf_size .
|
||||
The data is copied only if
|
||||
.I buf_size
|
||||
is greater than or equal to the size of the unwind data and
|
||||
.I buf
|
||||
is not NULL;
|
||||
otherwise, no data is copied, and the call succeeds,
|
||||
returning the size that would be needed to store the unwind data.
|
||||
|
||||
The first part of the unwind data contains an unwind table.
|
||||
The rest contains the associated unwind info in random order.
|
||||
The unwind table contains a table looking like:
|
||||
The rest contains the associated unwind information, in no particular order.
|
||||
The unwind table contains entries of the following form:
|
||||
|
||||
.nf
|
||||
u64 start; (64-bit address of start of function)
|
||||
|
|
@ -55,37 +72,47 @@ The unwind table contains a table looking like:
|
|||
u64 info; (BUF-relative offset to unwind info)
|
||||
.fi
|
||||
|
||||
An entry with a START address of zero is the end of table.
|
||||
For more information about the format you can see the IA-64
|
||||
Software Conventions and Runtime Architecture.
|
||||
An entry whose
|
||||
.I sytart
|
||||
value is zero indicates the end of the table.
|
||||
For more information about the format, see the
|
||||
.I IA-64 Software Conventions and Runtime Architecture
|
||||
manual.
|
||||
|
||||
.SH "RETURN VALUE"
|
||||
The
|
||||
.B sys_getunwind
|
||||
function returns size of unwind table.
|
||||
On success,
|
||||
.BR getunwind ()
|
||||
returns the size of unwind table.
|
||||
On error, \-1 is returned and
|
||||
.I errno
|
||||
is set to indicate the error.
|
||||
|
||||
.SH ERRORS
|
||||
The
|
||||
.B sys_getunwind
|
||||
function fails with
|
||||
.BR getunwind ()
|
||||
fails with the error
|
||||
.B EFAULT
|
||||
if the unwind info can't be stored in the space specified by
|
||||
the
|
||||
.I buf
|
||||
argument.
|
||||
.IR buf .
|
||||
|
||||
.SH AVAILABILITY
|
||||
This system call is available only on the IA-64 architecture.
|
||||
.SH VERSIONS
|
||||
This system call is available since Linux 2.4.
|
||||
|
||||
.SH APPLICATION USAGE
|
||||
This system call has been deprecated. It's highly recommended to get at the kernel's
|
||||
unwind info by the gate DSO. The address of the ELF header for this DSO
|
||||
is passed to user level via AT_SYSINFO_EHDR.
|
||||
.SH CONFORMING TO
|
||||
This system call is Linux specific,
|
||||
and is available only on the IA-64 architecture.
|
||||
|
||||
The system call is not available to application programs as a function;
|
||||
it can be called using the
|
||||
.BR syscall (2)
|
||||
function.
|
||||
.SH NOTES
|
||||
This system call has been deprecated.
|
||||
The modern way to obtain the kernel's unwind data is via the gate DSO.
|
||||
The address of the ELF header for this DSO
|
||||
is passed to user level via
|
||||
.BR AT_SYSINFO_EHDR
|
||||
(see
|
||||
.BR getauxval (3)).
|
||||
|
||||
Glibc does not provide a wrapper for this system call;
|
||||
in the unlikely event that you want to call it, use
|
||||
.BR syscall (2).
|
||||
|
||||
.SH "SEE ALSO"
|
||||
.BR syscall(2),
|
||||
.BR getauxval (3)
|
||||
|
|
|
|||
Loading…
Reference in New Issue