diff --git a/man2/getunwind.2 b/man2/getunwind.2 index 968e7f8a8..560d517f1 100644 --- a/man2/getunwind.2 +++ b/man2/getunwind.2 @@ -1,5 +1,6 @@ .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. .\" Written by Marcela Maslanova +.\" and Copyright 2013, Michael kerrisk .\" .\" 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 .B #include .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)