Permalink
Browse files

Tweak the manual page documenting the `dwarf_line*()` functions:

 * Keep functions and their descriptions in sorted order.
 * Mention the memory management protocol in the description for
   `dwarf_linesrc()` itself, instead of having a separate section.
 * Reword portions of the page text to be more concise.

Reviewed by:	   kaiwang27
Ticket(s):	   #97, #98, #99, #100, #101, #102, #103, #104

git-svn-id: https://elftoolchain.svn.sourceforge.net/svnroot/elftoolchain/trunk/libdwarf@1419 95820547-d848-0410-985e-9ae8fe0fa350
  • Loading branch information...
1 parent bfe1d0d commit 0e6a873e7a9601af1c3d75aaa90dcd848ba4a5a7 jkoshy committed Feb 6, 2011
Showing with 54 additions and 54 deletions.
  1. +54 −54 dwarf_lineno.3
View
108 dwarf_lineno.3
@@ -28,26 +28,20 @@
.Os
.Dt DWARF_LINENO 3
.Sh NAME
-.Nm dwarf_line_srcfileno ,
.Nm dwarf_lineaddr ,
.Nm dwarf_linebeginstatement ,
.Nm dwarf_lineblock ,
.Nm dwarf_lineendsequence ,
.Nm dwarf_lineno ,
.Nm dwarf_lineoff ,
-.Nm dwarf_linesrc
-.Nd retrieve line information assoicated with a line descriptor
+.Nm dwarf_linesrc ,
+.Nm dwarf_line_srcfileno
+.Nd retrieve information associated with a DWARF line descriptor
.Sh LIBRARY
.Lb libdwarf
.Sh SYNOPSIS
.In libdwarf.h
.Ft int
-.Fo dwarf_line_srcfileno
-.Fa "Dwarf_Line ln"
-.Fa "Dwarf_Unsigned *ret"
-.Fa "Dwarf_Error *err"
-.Fc
-.Ft int
.Fo dwarf_lineaddr
.Fa "Dwarf_Line ln"
.Fa "Dwarf_Addr *ret"
@@ -79,6 +73,7 @@
.Fc
.Ft int
.Fo dwarf_lineoff
+.Fa "Dwarf_Line ln"
.Fa "Dwarf_Signed *ret"
.Fa "Dwarf_Error *err"
.Fc
@@ -88,90 +83,96 @@
.Fa "char **ret"
.Fa "Dwarf_Error *err"
.Fc
+.Ft int
+.Fo dwarf_line_srcfileno
+.Fa "Dwarf_Line ln"
+.Fa "Dwarf_Unsigned *ret"
+.Fa "Dwarf_Error *err"
+.Fc
.Sh DESCRIPTION
These functions retrieve specific line information associated with
-the line descriptor referenced by argument
+the line descriptor specified by argument
.Ar ln ,
-and store it in the location pointed to by argument
+and stores it in the location pointed to by argument
.Ar ret .
If argument
.Ar err
is not NULL, it will be used to store error information in case of an
error.
.Pp
Function
-.Fn dwarf_line_srcfileno
-stores the index of the source file that contains the source line denoted
-by the line descriptor
-.Ar ln
-in the location pointed to by argument
-.Ar ret .
-The source file index starts from 1.
-.Pp
-Function
.Fn dwarf_lineaddr
-stores the program address corresponded to the source line denoted
-by the line descriptor
+stores the program address corresponding to the source line specified
+in argument
.Ar ln
-in the location pointed to by argument
+into the location pointed to by argument
.Ar ret .
.Pp
Function
.Fn dwarf_linebeginstatement
sets the location pointed to by argument
.Ar ret
-to 1 if the source line denoted by the line descriptor
+to 1 if the source line specified by the line descriptor
.Ar ln
-is the beginning of a statement, i.e., a recommanded breakpoint
-location, or 0 otherwise.
+is the beginning of a statement, or to 0 otherwise.
.Pp
Function
.Fn dwarf_lineblock
sets the location pointed to by argument
.Ar ret
-to 1 if the source line denoted by the line descriptor
+to 1 if the source line specified by the line descriptor
.Ar ln
-is the beginning of a basic block, or 0 otherwise.
+is the beginning of a basic block, or to 0 otherwise.
.Pp
Function
.Fn dwarf_lineendsequence
sets the location pointed to by argument
.Ar ret
-to 1 if the program address corresponded to the source line denoted by
-the line descriptor
+to 1 if the program address associated with the line descriptor
.Ar ln
-is the first byte after the end of a sequence of target machine
-instructions, or 0 otherwise.
+is the address immediately following the end of a sequence of target
+machine instructions, or to 0 otherwise.
.Pp
Function
.Fn dwarf_lineno
-stores the line number of the source line denoted by
-the line descriptor
-.Ar ln .
+stores the line number of the source line associated with the line
+descriptor
+.Ar ln
+into the location pointed to by argument
+.Ar ret .
.Pp
Function
.Fn dwarf_lineoff
-stores the column number within a line at which the source line
-denoted by the line descriptor
+stores the column number within a line associated with descriptor
.Ar ln
-begins. Column number begins from 1. The special column number
--1 indicates that the column number information is not available.
+into the location pointed to by argument
+.Ar ret .
+The retrieved column numbers are 1-based, with the value -1 indicating
+that column number information was not available.
.Pp
Function
.Fn dwarf_linesrc
-stores a pointer to a NUL-terminated string representing the name of
-the source file that contains the source line denoted by the line
-descriptor
+stores a pointer to a NUL-terminated string containing the source file
+name associated with line descriptor
.Ar ln
-in the location pointed to by argument
+into the location pointed to by argument
.Ar ret .
-The fullpath of the source file is retrieved if possible.
-.Ss Memory Management
+The full path of the source file is returned if possible.
The memory used for the source file name string is managed by the DWARF(3)
-library. The application should not attempt to directly free the name
-string. Portable code should indicate that the name string is to be freed
-by using
-.Xr dwarf_dealloc 3 .
+library and should not be directly freed by application code.
+Instead, portable code should use
+.Xr dwarf_dealloc 3
+to indicate that the string should be freed.
+.Pp
+Function
+.Fn dwarf_line_srcfileno
+stores the index of the source file associated with the line descriptor
+.Ar ln
+in the location pointed to by argument
+.Ar ret .
+The returned value is 1-based index into the array of source file
+names returned by
+.Xr dwarf_srcfiles 3 .
.Sh RETURN VALUES
On success, these functions returns
.Dv DW_DLV_OK .
@@ -189,14 +190,13 @@ or
.Va ret
was NULL.
.It Bq Er DW_DLE_LINE_FILE_NUM_BAD
-Function
-.Fn dwarf_linesrc
-could not find the source file name due to the source file number
-assoicated with line descriptor
+The source file name associated with the line descriptor
.Ar ln
-is invalid.
+could not be retrieved by function
+.Fn dwarf_linesrc .
.El
.Sh SEE ALSO
.Xr dwarf 3 ,
+.Xr dwarf_dealloc 3 ,
.Xr dwarf_srcfiles 3 ,
.Xr dwarf_srclines 3

0 comments on commit 0e6a873

Please sign in to comment.