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:
parent
4288c61864
commit
fe828902eb
|
@ -1,5 +1,6 @@
|
||||||
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
||||||
.\" Written by Marcela Maslanova <mmaslano@redhat.com>
|
.\" 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
|
.\" Permission is granted to make and distribute verbatim copies of this
|
||||||
.\" manual provided the copyright notice and this permission notice are
|
.\" 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.
|
.\" 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
|
.SH NAME
|
||||||
getunwind \- copy the unwind data to caller's buffer
|
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 <syscall.h>
|
||||||
.B #include <linux/unwind.h>
|
.B #include <linux/unwind.h>
|
||||||
.sp
|
.sp
|
||||||
.BI "long getunwind (void " *buf ", size_t " buf_size );
|
.BI "long getunwind(void " *buf ", size_t " buf_size );
|
||||||
.fi
|
.fi
|
||||||
|
|
||||||
|
.IR Note :
|
||||||
|
There is no glibc wrapper for this system call; see NOTES.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
|
.I Note: this function is obsolete.
|
||||||
|
|
||||||
The
|
The
|
||||||
.B sys_getunwind
|
IA-64-specific
|
||||||
function returns size of unwind table, which describes gate page (kernel code that
|
.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).
|
is mapped into user space).
|
||||||
|
|
||||||
The unwind data is copied to the buffer \fIbuf\fR, which has size \fIbuf_size\fR.
|
The size of the buffer
|
||||||
The data is copied
|
.I buf
|
||||||
only if \fIbuf_size\fR is greater than or equal to the size of the
|
is specified in
|
||||||
unwind data and \fIbuf\fR is not NULL.
|
.IR buf_size .
|
||||||
The system call returns the size of the unwind data in both cases.
|
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 first part of the unwind data contains an unwind table.
|
||||||
The rest contains the associated unwind info in random order.
|
The rest contains the associated unwind information, in no particular order.
|
||||||
The unwind table contains a table looking like:
|
The unwind table contains entries of the following form:
|
||||||
|
|
||||||
.nf
|
.nf
|
||||||
u64 start; (64-bit address of start of function)
|
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)
|
u64 info; (BUF-relative offset to unwind info)
|
||||||
.fi
|
.fi
|
||||||
|
|
||||||
An entry with a START address of zero is the end of table.
|
An entry whose
|
||||||
For more information about the format you can see the IA-64
|
.I sytart
|
||||||
Software Conventions and Runtime Architecture.
|
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"
|
.SH "RETURN VALUE"
|
||||||
The
|
On success,
|
||||||
.B sys_getunwind
|
.BR getunwind ()
|
||||||
function returns size of unwind table.
|
returns the size of unwind table.
|
||||||
|
On error, \-1 is returned and
|
||||||
|
.I errno
|
||||||
|
is set to indicate the error.
|
||||||
|
|
||||||
.SH ERRORS
|
.SH ERRORS
|
||||||
The
|
.BR getunwind ()
|
||||||
.B sys_getunwind
|
fails with the error
|
||||||
function fails with
|
|
||||||
.B EFAULT
|
.B EFAULT
|
||||||
if the unwind info can't be stored in the space specified by
|
if the unwind info can't be stored in the space specified by
|
||||||
the
|
.IR buf .
|
||||||
.I buf
|
|
||||||
argument.
|
|
||||||
|
|
||||||
.SH AVAILABILITY
|
.SH VERSIONS
|
||||||
This system call is available only on the IA-64 architecture.
|
This system call is available since Linux 2.4.
|
||||||
|
|
||||||
.SH APPLICATION USAGE
|
.SH CONFORMING TO
|
||||||
This system call has been deprecated. It's highly recommended to get at the kernel's
|
This system call is Linux specific,
|
||||||
unwind info by the gate DSO. The address of the ELF header for this DSO
|
and is available only on the IA-64 architecture.
|
||||||
is passed to user level via AT_SYSINFO_EHDR.
|
|
||||||
|
|
||||||
The system call is not available to application programs as a function;
|
.SH NOTES
|
||||||
it can be called using the
|
This system call has been deprecated.
|
||||||
.BR syscall (2)
|
The modern way to obtain the kernel's unwind data is via the gate DSO.
|
||||||
function.
|
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"
|
.SH "SEE ALSO"
|
||||||
.BR syscall(2),
|
.BR getauxval (3)
|
||||||
|
|
Loading…
Reference in New Issue