\chapter{A Consumer Library Interface to DWARF }
\hypertarget{index}{}\label{index}\index{A Consumer Library Interface to DWARF@{A Consumer Library Interface to DWARF}}
\etocsetnexttocdepth{2}
\localtableofcontents
\begin{DoxyAuthor}{Author}
David Anderson 
\end{DoxyAuthor}
\begin{DoxyCopyright}{Copyright}
This work is licensed under the Creative Commons Attribution 4.\+0 International License. To view a copy of this license, visit \href{http://creativecommons.org/licenses/by/4.0/}{\texttt{http:\+/\+/\+creativecommons.\+org/\+licenses/\+by/\+4.\+0/\+}} or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. 
\end{DoxyCopyright}
\begin{DoxyDate}{Date}
2026-\/03-\/04 v2.\+3.\+1
\end{DoxyDate}
\hypertarget{index_draft}{}\doxysection{\texorpdfstring{Suggestions for improvement are welcome.}{Suggestions for improvement are welcome.}}\label{index_draft}
Your thoughts on the document?

A) Are the section and subsection titles on Main Page meaningful to you?

B) Are the titles on the Modules page meaningful to you?

Anything else you find misleading or confusing? Send suggestions to ( libdwarf (at) linuxmail with final characters .org ). Sorry about the simple obfuscation to keep bots away.

Thanks in advance for any suggestions.\hypertarget{index_clone_command}{}\doxysection{\texorpdfstring{Downloading Libdwarf}{Downloading Libdwarf}}\label{index_clone_command}
Project page is at {\bfseries{\href{https://github.com/davea42/libdwarf-code}{\texttt{https:\+/\+/\+github.\+com/\+davea42/\+libdwarf-\/code}}}}

There is a Releases area on the project page, click Latest and you will be presented with options to download the source in three different forms.

For details on licensing, see COPYING in the files list.

README.\+md may be of interest (automatically shown on the project page on github).

Examples of using libdwarf are in \doxylink{checkexamples_8c}{doc/\+checkexamples.\+c} and src/\+bin/\+dwarfexamples.

To download source, one could do:\+

{\bfseries{git clone \href{https://github.com/davea42/libdwarf-code}{\texttt{https:\+/\+/\+github.\+com/\+davea42/\+libdwarf-\/code}} code}}

Some tests simply assume the project source base name is {\bfseries{code}} which is why the above is as shown. This is a grave historical misfeature that needs to be fixed in the test scripts.\hypertarget{index_dwsec_intro}{}\doxysection{\texorpdfstring{Introduction}{Introduction}}\label{index_dwsec_intro}
This document describes an interface to {\itshape libdwarf}, a library of functions to provide access to DWARF debugging information records, DWARF line number information, DWARF address range and global names information, weak names information, DWARF frame description information, DWARF static function names, DWARF static variables, and DWARF type information. In addition the library provides access to several object sections (created by compiler writers and for debuggers) related to debugging but not mentioned in any DWARF standard.

The DWARF Standard has long mentioned the "{}\+Unix \+International Programming Languages Special \+Interest Group"{} (PLSIG), under whose auspices the DWARF committee was formed around 1991. "{}\+Unix \+International"{} was disbanded in the 1990s and no longer exists.

The DWARF committee published DWARF2 July 27, 1993, DWARF3 in 2005, DWARF4 in 2010, and DWARF5 in 2017.

In the mid 1990s this document and the library it describes (which the committee never endorsed, having decided not to endorse or approve any particular library interface) was made available on the internet by Silicon Graphics, Inc.

In 2005 the DWARF committee began an affiliation with Free\+Standards.\+org. In 2007 Free\+Standards.\+org merged with The Linux Foundation. The DWARF committee dropped its affiliation with Free\+Standards.\+org in 2007 and established the dwarfstd.\+org website.

\begin{DoxySeeAlso}{See also}
\href{https://www.dwarfstd.org}{\texttt{https:\+/\+/\+www.\+dwarfstd.\+org}} for current information on standardization activities and a copy of the standard.
\end{DoxySeeAlso}
\hypertarget{index_dwsec_threadsafety}{}\doxysection{\texorpdfstring{Thread Safety}{Thread Safety}}\label{index_dwsec_threadsafety}
Libdwarf can safely open multiple \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} pointers simultaneously but all such \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} pointers must be opened within the same thread. And all {\itshape libdwarf} calls must be made from within that single (same) thread.\hypertarget{index_dwsec_error}{}\doxysection{\texorpdfstring{Error Handling in libdwarf}{Error Handling in libdwarf}}\label{index_dwsec_error}
Essentially every {\itshape libdwarf} call could involve dealing with an error (possibly data corruption in the object file). Here we explain the two main approaches the library provides (though we think only one of them is truly appropriate except in toy programs). In all cases where the library returns an error code (almost every library function does) the caller should check whether the returned integer is DW\+\_\+\+DLV\+\_\+\+OK, DW\+\_\+\+DLV\+\_\+\+ERROR, or DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY and then act accordingly.

{\bfseries{A) The recommended approach}} is to define a \doxylink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error} and initialize it to 0.


\begin{DoxyCode}{0}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\_Error}}\ error\ =\ 0;}

\end{DoxyCode}
 Then, in every call where there is a \doxylink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error} argument pass its address. For example:\+ 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ res\ =\ \doxymbox{\hyperlink{group__dieentry_ga2edb7c81f0dde72c4794808828ef4d91}{dwarf\_tag}}(die,DW\_TAG\_compile\_unit,\&error);}

\end{DoxyCode}


The possible return values to res are, in general:\+ 
\begin{DoxyCode}{0}
\DoxyCodeLine{DW\_DLV\_OK}
\DoxyCodeLine{DW\_DLV\_NO\_ENTRY}
\DoxyCodeLine{DW\_DLV\_ERROR}

\end{DoxyCode}


If {\bfseries{DW\+\_\+\+DLV\+\_\+\+ERROR}} is returned then error is set (by the library) to a pointer to important details about the error and the library will not pass back any data through other pointer arguments. If {\bfseries{DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY}} is returned the error argument is ignored by the library and the library will not pass back any data through pointer arguments. If {\bfseries{DW\+\_\+\+DLV\+\_\+\+OK}} is returned argument pointers that are defined as ways to return data to your code are used and values are set in your data by the library.

Some functions cannot possibly return some of these three values. As defined later for each function.

{\bfseries{B) An alternative (not recommended)}} approach is to pass NULL to the error argument.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ res\ =\ \doxymbox{\hyperlink{group__dieentry_ga2edb7c81f0dde72c4794808828ef4d91}{dwarf\_tag}}(die,DW\_TAG\_compile\_unit,NULL);}

\end{DoxyCode}


If your initialization provided an \textquotesingle{}errhand\textquotesingle{} function pointer argument (see below) the library will call errhand if an error is encountered. (Your errhand function could exit if you so choose.)

The the library will then return DW\+\_\+\+DLV\+\_\+\+ERROR, though you will have no way to identify what the error was. Could be a malloc fail or data corruption or an invalid argument to the call, or something else.

That is the whole picture. The library never calls exit() under any circumstances.\hypertarget{index_dw_errorinit}{}\doxysubsection{\texorpdfstring{Error Handling at Initialization}{Error Handling at Initialization}}\label{index_dw_errorinit}
Each initialization call (for example) 
\begin{DoxyCode}{0}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\_Debug}}\ \ \ dbg\ =\ 0;}
\DoxyCodeLine{\textcolor{keyword}{const}\ \textcolor{keywordtype}{char}\ \ \ *path\ =\ \textcolor{stringliteral}{"{}myobjectfile"{}};}
\DoxyCodeLine{\textcolor{keywordtype}{char}\ \ \ \ \ \ \ \ \ *true\_path\ =\ 0;}
\DoxyCodeLine{\textcolor{keywordtype}{unsigned}\ \textcolor{keywordtype}{int}\ \ true\_pathlen\ =\ 0;}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_ga6de1c2929cebfae36804315f7232cb19}{Dwarf\_Handler}}\ errhand\ =\ 0;}
\DoxyCodeLine{\doxymbox{\hyperlink{group__basicdatatypes_ga376c1939313af42401fc67bc998fdd2c}{Dwarf\_Ptr}}\ \ \ \ \ errarg\ =\ 0;}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\_Error}}\ \ \ error\ =\ 0;}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ \ \ \ \ \ \ \ \ \ \ res\ =\ 0;}
\DoxyCodeLine{}
\DoxyCodeLine{res\ =\ \doxymbox{\hyperlink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\_init\_path}}(path,true\_path,true\_pathlen,}
\DoxyCodeLine{\ \ \ \ DW\_GROUPNUMBER\_ANY,errhand,errarg,\&dbg,\&error);}

\end{DoxyCode}
 has two arguments that appear nowhere else in the library. 
\begin{DoxyCode}{0}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_ga6de1c2929cebfae36804315f7232cb19}{Dwarf\_Handler}}\ errhand}
\DoxyCodeLine{\doxymbox{\hyperlink{group__basicdatatypes_ga376c1939313af42401fc67bc998fdd2c}{Dwarf\_Ptr}}\ \ \ \ \ errarg}

\end{DoxyCode}


For the {\bfseries{recommended A)}} approach:\+

Just pass NULL to both those arguments. If the initialization call returns DW\+\_\+\+DLV\+\_\+\+ERROR you should then call 
\begin{DoxyCode}{0}
\DoxyCodeLine{\doxymbox{\hyperlink{group__dwarferror_gaa6b5e63031b88831d0f40051f7f3e1c8}{dwarf\_dealloc\_error}}(dbg,error);}

\end{DoxyCode}
 to free the \doxylink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error} data because \doxylink{group__initfunctions_ga14a505c07ee5481401735f280f719454}{dwarf\+\_\+finish()} does not clean up a dwarf-\/init error. This works even though {\itshape dbg} will be NULL.

For the {\bfseries{not recommended B)}} approach:\+

Because dw\+\_\+errarg is a general pointer one could create a struct with data of interest and use a pointer to the struct as the dw\+\_\+errarg. Or one could use an integer or NULL, it just depends what you want to do in the \doxylink{group__allstructs_ga6de1c2929cebfae36804315f7232cb19}{Dwarf\+\_\+\+Handler} function you write.

If you wish to provide a dw\+\_\+errhand, define a function (this first example is not a good choice as it terminates the application!). 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void}\ bad\_dw\_errhandler(\doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\_Error}}\ error,\doxymbox{\hyperlink{group__basicdatatypes_ga376c1939313af42401fc67bc998fdd2c}{Dwarf\_Ptr}}\ ptr)}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ printf(\textcolor{stringliteral}{"{}ERROR\ Exit\ on\ \%lx\ due\ to\ error\ 0x\%lx\ \%s\(\backslash\)n"{}},}
\DoxyCodeLine{\ \ \ \ \ \ \ \ (\textcolor{keywordtype}{unsigned}\ \textcolor{keywordtype}{long})ptr,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ (\textcolor{keywordtype}{unsigned}\ \textcolor{keywordtype}{long})\doxymbox{\hyperlink{group__dwarferror_ga494aa4910e76c78c8e39de5003f30853}{dwarf\_errno}}(error),}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \doxymbox{\hyperlink{group__dwarferror_ga61e9111a5ffc64b7e4cb338e3ed07f6e}{dwarf\_errmsg}}(error));}
\DoxyCodeLine{\ \ \ \ exit(1)}
\DoxyCodeLine{\}}

\end{DoxyCode}
 and pass bad\+\_\+dw\+\_\+errhandler (as a function pointer, no parentheses).

The \doxylink{group__basicdatatypes_ga376c1939313af42401fc67bc998fdd2c}{Dwarf\+\_\+\+Ptr} argument your error handler function receives is the value you passed in as dw\+\_\+errarg, and can be anything, it allows you to associate the callback with a particular dwarf\+\_\+init\texorpdfstring{$\ast$}{*} call if you wish to make such an association.

By doing an exit() you guarantee that your application abruptly stops. This is only acceptable in toy or practice programs.

A better dw\+\_\+errhand function is 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void}\ my\_dw\_errhandler(\doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\_Error}}\ error,\doxymbox{\hyperlink{group__basicdatatypes_ga376c1939313af42401fc67bc998fdd2c}{Dwarf\_Ptr}}\ ptr)}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{/*\ \ Clearly\ one\ could\ write\ to\ a\ log\ file\ or\ do}}
\DoxyCodeLine{\textcolor{comment}{\ \ \ \ \ \ \ \ whatever\ the\ application\ finds\ useful.\ */}}
\DoxyCodeLine{\ \ \ \ printf(\textcolor{stringliteral}{"{}ERROR\ on\ \%lx\ due\ to\ error\ 0x\%lx\ \%s\(\backslash\)n"{}},}
\DoxyCodeLine{\ \ \ \ \ \ \ \ (\textcolor{keywordtype}{unsigned}\ \textcolor{keywordtype}{long})ptr,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ (\textcolor{keywordtype}{unsigned}\ \textcolor{keywordtype}{long})\doxymbox{\hyperlink{group__dwarferror_ga494aa4910e76c78c8e39de5003f30853}{dwarf\_errno}}(error),}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \doxymbox{\hyperlink{group__dwarferror_ga61e9111a5ffc64b7e4cb338e3ed07f6e}{dwarf\_errmsg}}(error));}
\DoxyCodeLine{\}}

\end{DoxyCode}
 because it returns rather than exiting. It is not ideal. The DW\+\_\+\+DLV\+\_\+\+ERROR code is returned from {\itshape libdwarf} and your code can do what it likes with the error situation. The library will continue from the error and will return an error code on returning to your libdwarf call ... but the calling function will not know what the error was.


\begin{DoxyCode}{0}
\DoxyCodeLine{\doxymbox{\hyperlink{group__basicdatatypes_ga376c1939313af42401fc67bc998fdd2c}{Dwarf\_Ptr}}\ x\ =\ address\ of\ some\ \textcolor{keyword}{struct\ }I\ want\ in\ the\ errhandler;}
\DoxyCodeLine{res\ =\ \doxymbox{\hyperlink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\_init\_path}}(...,my\_dw\_errhandler,x,...\ );}
\DoxyCodeLine{\textcolor{keywordflow}{if}\ (res\ ==\ ...)}

\end{DoxyCode}
 If you do not wish to provide a dw\+\_\+errhand, just pass both arguments as NULL.\hypertarget{index_dw_errorcall}{}\doxysubsection{\texorpdfstring{Error Handling Everywhere}{Error Handling Everywhere}}\label{index_dw_errorcall}
So let us examine a simple case where anything could happen. We are taking the {\bfseries{recommended A)}} method of using a non-\/null Dwarf\+\_\+\+Error\texorpdfstring{$\ast$}{*}:\+


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ func(Dwarf\_Dbg\ dbg,\doxymbox{\hyperlink{group__allstructs_ga3a3759c3047d78dba9f590d5e5893be5}{Dwarf\_Die}}\ die,\ \doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\_Error}}*\ error)\ \{}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__allstructs_ga3a3759c3047d78dba9f590d5e5893be5}{Dwarf\_Die}}\ newdie\ =\ 0;}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{int}\ \ \ \ \ \ \ res\ =\ 0;}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ res\ =\ \doxymbox{\hyperlink{group__compilationunit_gac9755be1dca4cc32c3a477d1f10f35f4}{dwarf\_siblingof\_c}}(die,\&newdie,error);}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{if}\ (res\ !=\ DW\_DLV\_OK)\ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{/*\ \ Whether\ DW\_DLV\_ERROR\ or\ DW\_DLV\_NO\_ENTRY}}
\DoxyCodeLine{\textcolor{comment}{\ \ \ \ \ \ \ \ \ \ \ \ (the\ latter\ is\ actually\ impossible}}
\DoxyCodeLine{\textcolor{comment}{\ \ \ \ \ \ \ \ \ \ \ \ for\ this\ function)\ returning\ res\ is\ the}}
\DoxyCodeLine{\textcolor{comment}{\ \ \ \ \ \ \ \ \ \ \ \ appropriate\ default\ thing\ to\ do.\ */}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{keywordflow}{return}\ res;}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{/*\ \ Do\ something\ with\ newdie.\ */}}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__compilationunit_ga44bb7c253ff53b3edd9c4e012ec15a08}{dwarf\_dealloc\_die}}(newdie);}
\DoxyCodeLine{\ \ \ \ newdie\ =\ 0;\ \textcolor{comment}{/*\ A\ good\ habit...\ */}}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{return}\ DW\_DLV\_OK;}
\DoxyCodeLine{\}}

\end{DoxyCode}
\hypertarget{index_DW_DLV_OK}{}\doxysubsubsection{\texorpdfstring{DW\+\_\+\+DLV\+\_\+\+OK}{DW\+\_\+\+DLV\+\_\+\+OK}}\label{index_DW_DLV_OK}
When res == DW\+\_\+\+DLV\+\_\+\+OK newdie is a valid pointer and when appropriate we should do dwarf\+\_\+dealloc\+\_\+die(newdie). For other {\itshape libdwarf} calls the meaning depends on the function called, so read the description of the function you called for more information.\hypertarget{index_DW_DLV_NO_ENTRY}{}\doxysubsubsection{\texorpdfstring{DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY}{DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY}}\label{index_DW_DLV_NO_ENTRY}
When res == DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY then newdie is not set and there is no error. It means die was the last of a siblinglist. For other {\itshape libdwarf} calls the meaning depends on the function called, so read the description of the function you called for more information.\hypertarget{index_DW_DLV_ERROR}{}\doxysubsubsection{\texorpdfstring{DW\+\_\+\+DLV\+\_\+\+ERROR}{DW\+\_\+\+DLV\+\_\+\+ERROR}}\label{index_DW_DLV_ERROR}
When res == DW\+\_\+\+DLV\+\_\+\+ERROR Something bad happened. The only way to know what happened is to examine the \texorpdfstring{$\ast$}{*}error as in 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ ev\ =\ \doxymbox{\hyperlink{group__dwarferror_ga494aa4910e76c78c8e39de5003f30853}{dwarf\_errno}}(*error);}
\DoxyCodeLine{or}
\DoxyCodeLine{\textcolor{keywordtype}{char}\ *\ msg\ \ =\ \doxymbox{\hyperlink{group__dwarferror_ga61e9111a5ffc64b7e4cb338e3ed07f6e}{dwarf\_errmsg}}(*error);}

\end{DoxyCode}
 or both and report that somehow.

The above three values are the only returns possible from the great majority of {\itshape libdwarf} functions, and for these functions the return type is always {\bfseries{int}} .

If it is a decently large or long-\/running program then you want to free any local memory you allocated and return res. If it is a small or experimental program print something and exit (possibly leaking memory).

If you want to discard the error report from the \doxylink{group__compilationunit_gac9755be1dca4cc32c3a477d1f10f35f4}{dwarf\+\_\+siblingof\+\_\+c()} call then possibly do 
\begin{DoxyCode}{0}
\DoxyCodeLine{\doxymbox{\hyperlink{group__dwarferror_gaa6b5e63031b88831d0f40051f7f3e1c8}{dwarf\_dealloc\_error}}(dbg,*error);}
\DoxyCodeLine{*error\ =\ 0;}
\DoxyCodeLine{\textcolor{keywordflow}{return}\ DW\_DLV\_OK;}

\end{DoxyCode}


Except in a special case involving function \doxylink{group__miscellaneous_gaaeeaaed1a0b21858990691ae5441fb32}{dwarf\+\_\+set\+\_\+de\+\_\+alloc\+\_\+flag()} (which you will not usually call), any \doxylink{group__dwarfdealloc_gae16282e9709d62dd0cb6b61b11ce36eb}{dwarf\+\_\+dealloc()} that is needed will happen automatically when you call \doxylink{group__initfunctions_ga14a505c07ee5481401735f280f719454}{dwarf\+\_\+finish()}.\hypertarget{index_A}{}\doxysubsubsection{\texorpdfstring{Slight Performance Enhancement}{Slight Performance Enhancement}}\label{index_A}
Very long running library access programs using relevant appropriate dwarf\+\_\+dealloc calls should consider calling dwarf\+\_\+set\+\_\+de\+\_\+alloc\+\_\+flag(0). Using this one could get a performance enhancement of perhaps five percent in {\itshape libdwarf} CPU time and a reduction in memory use.

Be sure to test using valgrind (at runtime) or the gcc option -\/fsanitize at compile time and run tests appropriately to ensure your code really does the extra dwarf\+\_\+dealloc calls needed since when using dwarf\+\_\+set\+\_\+de\+\_\+alloc\+\_\+flag(0) \doxylink{group__initfunctions_ga14a505c07ee5481401735f280f719454}{dwarf\+\_\+finish()} does only limited cleanup.\hypertarget{index_dwsec_cuplan}{}\doxysection{\texorpdfstring{Extracting Data Per Compilation Unit}{Extracting Data Per Compilation Unit}}\label{index_dwsec_cuplan}
The library is designed to run a single pass through the set of Compilation Units (CUs), via a sequence of calls to \doxylink{group__compilationunit_ga282a397fc2095bd2939d486b232e3cc2}{dwarf\+\_\+next\+\_\+cu\+\_\+header\+\_\+e()}. (\doxylink{group__compilationunit_ga474f73416ef468aab00dffbbdd149b0e}{dwarf\+\_\+next\+\_\+cu\+\_\+header\+\_\+d()} is supported but its use requires that it be immediately followed by a call to \doxylink{group__compilationunit_gab8ae0bd010de9b7dca65f761b2c395e1}{dwarf\+\_\+siblingof\+\_\+b()}. see \doxylink{group__compilationunit_ga474f73416ef468aab00dffbbdd149b0e}{dwarf\+\_\+next\+\_\+cu\+\_\+header\+\_\+d()}. )

Within a CU opened with \doxylink{group__compilationunit_ga282a397fc2095bd2939d486b232e3cc2}{dwarf\+\_\+next\+\_\+cu\+\_\+header\+\_\+e()} do something (if desired) on the CU\+\_\+\+DIE returned, and call \doxylink{group__compilationunit_gab31f79265b1d39aff271b1780c6d0eb9}{dwarf\+\_\+child()} on the CU\+\_\+\+DIE to begin recursing through all DIEs. If you save the CU\+\_\+\+DIE you can repeat passes beginning with \doxylink{group__compilationunit_gab31f79265b1d39aff271b1780c6d0eb9}{dwarf\+\_\+child()} on the CU\+\_\+\+DIE, though it almost certainly faster to remember, in your data structures, what you need from the first pass.

The general plan:\+


\begin{DoxyCode}{0}
\DoxyCodeLine{create\ your\ local\ data\ structure(s)}
\DoxyCodeLine{}
\DoxyCodeLine{A.\ \ Check\ your\ local\ data\ structures\ to\ see\ \textcolor{keywordflow}{if}}
\DoxyCodeLine{\ \ \ \ you\ have\ what\ you\ need}
\DoxyCodeLine{B.\ \ If\ sufficient\ data\ present\ act\ on\ it,}
\DoxyCodeLine{\ \ \ \ ensuring\ your\ data\ structures\ are\ kept\ \textcolor{keywordflow}{for}}
\DoxyCodeLine{\ \ \ \ further\ use.}
\DoxyCodeLine{C.\ \ Otherwise\ Read\ a\ CU,\ recording\ relevant\ data}
\DoxyCodeLine{\ \ \ \ in\ your\ structures\ and\ loop\ back\ to\ A.}

\end{DoxyCode}


For an example (best approach) \begin{DoxySeeAlso}{See also}
\doxylink{group__examplecuhdre}{Example walking CUs(e)} or (second-\/best approach) 

\doxylink{group__examplecuhdrd}{Example walking CUs(d)} Write your code to record relevant (to you) information from each CU as you go so your code has no need for a second pass through the CUs. This is much much faster than allowing multiple passes would be.
\end{DoxySeeAlso}
\hypertarget{index_dwsec_linetabreg}{}\doxysection{\texorpdfstring{Line Table Registers}{Line Table Registers}}\label{index_dwsec_linetabreg}
Line Table Registers

Please refer to the DWARF5 Standard for details. The line table registers are named in Section 6.\+2.\+2 State Machine Registers and are not much changed from DWARF2.

Certain functions on \doxylink{group__allstructs_gae4486812c6f1ec8cc2ec475149c256c0}{Dwarf\+\_\+\+Line} data return values for these \textquotesingle{}registers\textquotesingle{} as these are the data available for debuggers and other tools to relate a code address to a source file name and possibly also to a line number and column-\/number within the source file.


\begin{DoxyCode}{0}
\DoxyCodeLine{address}
\DoxyCodeLine{op\_index}
\DoxyCodeLine{file}
\DoxyCodeLine{line}
\DoxyCodeLine{column}
\DoxyCodeLine{is\_stmt}
\DoxyCodeLine{basic\_block}
\DoxyCodeLine{end\_sequence}
\DoxyCodeLine{prologue\_end}
\DoxyCodeLine{epilogue\_begin}
\DoxyCodeLine{isa}
\DoxyCodeLine{discriminator}

\end{DoxyCode}
\hypertarget{index_dwsec_independentsec}{}\doxysection{\texorpdfstring{Reading Special Sections Independently}{Reading Special Sections Independently}}\label{index_dwsec_independentsec}
DWARF defines (in each version of DWARF) sections which have a somewhat special character. These are referenced from compilation units and other places and the Standard does not forbid blocks of random bytes at the start or end or between the areas referenced from elsewhere.

Sometimes compilers (or linkers) leave trash behind as a result of optimizations. If there is a lot of space wasted that way it is a quality of implementation issue. But usually the wasted space, if any, is small.

Compiler writers or others may be interested in looking at these sections independently so {\itshape libdwarf} provides functions that allow reading the sections without reference to what references them.

\doxylink{group__abbrev}{Abbreviations can be read independently }

\doxylink{group__string}{Strings can be read independently }

\doxylink{group__str__offsets}{String Offsets can be read independently }

\doxylink{group__debugaddr}{The addr table can be read independently }

Those functions allow starting at byte 0 of the section and provide a length so you can calculate the next section offset to call or refer to.

Usually that works fine. If there is some random data somewhere outside of referenced areas or the data format is a gcc extension of an early DWARF version the reader function may fail, returning DW\+\_\+\+DLV\+\_\+\+ERROR. Such an error is neither a compiler bug nor a {\itshape libdwarf} bug.\hypertarget{index_frameregs}{}\doxysection{\texorpdfstring{Special Frame Registers}{Special Frame Registers}}\label{index_frameregs}
In dealing with .debug\+\_\+frame or .eh\+\_\+frame there are five values that must be set unless one has relatively few registers in the target ABI (anything under 188 registers, see \doxylink{dwarf_8h}{dwarf.\+h} DW\+\_\+\+FRAME\+\_\+\+LAST\+\_\+\+REG\+\_\+\+NUM for this default).

The requirements stem from the design of the section. See the DWARF5 Standard for details. The .debug\+\_\+frame section is basically the same from DWARF2 on. The .eh\+\_\+frame section is similar to .debug\+\_\+frame but is intended to support exception handling and has fields and data not present in .debug\+\_\+frame.

Keep in mind that register values correspond to columns in the theoretical fully complete line table of a row per pc and a column per register.

There is no time or space penalty in setting {\bfseries{Undefined\+\_\+\+Value,}} {\bfseries{Same\+\_\+\+Value,}} and {\bfseries{CFA\+\_\+\+Column}} much larger than the {\bfseries{Table\+\_\+\+Size}}.

Here are the five values.

{\bfseries{Table\+\_\+\+Size:\+}} This sets the number of columns in the theoretical table. It starts at DW\+\_\+\+FRAME\+\_\+\+LAST\+\_\+\+REG\+\_\+\+NUM which defaults to 188. This is the only value you might need to change, given the defaults of the others are set reasonably large by default. Setting this higher than necessary wastes cpu time and memory space.

{\bfseries{Undefined\+\_\+\+Value:\+}} A register number that means the register value is undefined. For example due to a call clobbering the register. DW\+\_\+\+FRAME\+\_\+\+UNDEFINED\+\_\+\+VAL defaults to 12288. There no such column in the table.

{\bfseries{Same\+\_\+\+Value:\+}} A register number that means the register value is the same as the value at the call. Nothing can have clobbered it. DW\+\_\+\+FRAME\+\_\+\+SAME\+\_\+\+VAL defaults to 12289. There no such column in the table.

{\bfseries{Initial\+\_\+\+Value:\+}} The value must be either DW\+\_\+\+FRAME\+\_\+\+UNDEFINED\+\_\+\+VAL or DW\+\_\+\+FRAME\+\_\+\+SAME\+\_\+\+VAL to represent how most registers are to be thought of at a function call. This is a property of the ABI and instruction set. Specific frame instructions in the CIE or FDE will override this for registers not matching this value.

{\bfseries{CFA\+\_\+\+Column:\+}} A number for the CFA. Defined so we can use a register number to refer to it. DW\+\_\+\+FRAME\+\_\+\+CFA\+\_\+\+COL defaults to 12290. There no such column in the table. See \doxylink{libdwarf_8h}{libdwarf.\+h} struct \doxylink{struct_dwarf___regtable3__s}{Dwarf\+\_\+\+Regtable3\+\_\+s} member rt3\+\_\+cfa\+\_\+rule or function \doxylink{group__frame_ga294a626cd6b89ce9ad020f4e3929f630}{dwarf\+\_\+get\+\_\+fde\+\_\+info\+\_\+for\+\_\+cfa\+\_\+reg3\+\_\+b()} or function \doxylink{group__frame_gad61d9e9b0724b08706e607d4d37fa5a0}{dwarf\+\_\+get\+\_\+fde\+\_\+info\+\_\+for\+\_\+cfa\+\_\+reg3\+\_\+c()} .

A set of functions allow these to be changed at runtime. The set should be called (if needed) immediately after initializing a \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} and before any other calls on that \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug}. If just one value (for example, Table\+\_\+\+Size) needs altering, then just call that single function.

For the library accessing frame data to work properly there are certain invariants that must be true once the set of functions have been called.

REQUIRED:\+ 
\begin{DoxyCode}{0}
\DoxyCodeLine{Table\_Size\ \ \ \ \ \ >\ the\ number\ of\ registers\ in\ the\ ABI.}
\DoxyCodeLine{Undefined\_Value\ !=\ Same\_Value}
\DoxyCodeLine{CFA\_Column\ \ \ \ \ \ !=\ Undefined\_value}
\DoxyCodeLine{CFA\_Column\ \ \ \ \ \ !=\ Same\_value}
\DoxyCodeLine{Initial\_Value\ \ \ ==\ Same\_Value\ ||}
\DoxyCodeLine{\ \ \ \ (Initial\_Value\ ==\ Undefined\_value)}
\DoxyCodeLine{Undefined\_Value\ >\ Table\_Size}
\DoxyCodeLine{Same\_Value\ \ \ \ \ \ >\ Table\_Size}
\DoxyCodeLine{CFA\_Column\ \ \ \ \ \ >\ Table\_Size}

\end{DoxyCode}


If these conditions are not honored the library will return a DW\+\_\+\+DLV\+\_\+\+ERROR code rather than use an improper set of values.\hypertarget{index_dwsec_pubnames}{}\doxysection{\texorpdfstring{.debug\+\_\+pubnames etc DWARF2-\/\+DWARF4}{.debug\+\_\+pubnames etc DWARF2-\/\+DWARF4}}\label{index_dwsec_pubnames}
Each section consists of a header for a specific compilation unit (CU) followed by an a set of tuples, each tuple consisting of an offset of a compilation unit followed by a null-\/terminated namestring. The tuple set is ended by a 0,0 pair. Then followed with the data for the next CU and so on.

The function set provided for each such section allows one to print all the section data as it literally appears in the section (with headers and tuples) or to treat it as a single array with CU data columns.

Each has a set of 6 functions.


\begin{DoxyCode}{0}
\DoxyCodeLine{Section\ \ \ \ \ \ \ \ \ \ \textcolor{keyword}{typename}\ \ \ \ \ \ Standard}
\DoxyCodeLine{.debug\_pubnames\ \ \doxymbox{\hyperlink{group__allstructs_ga59a6e779b3b390cf4f234c9edee87008}{Dwarf\_Global}}\ \ DWARF2-\/DWARF4}
\DoxyCodeLine{.debug\_pubtypes\ \ \doxymbox{\hyperlink{group__allstructs_ga59a6e779b3b390cf4f234c9edee87008}{Dwarf\_Global}}\ \ DWARF3,DWARF4}

\end{DoxyCode}


These sections are accessed calling \doxylink{group__pubnames_gaef3a5b4e40f2f1e65c42eeff102733aa}{dwarf\+\_\+globals\+\_\+by\+\_\+type()} using type of DW\+\_\+\+GL\+\_\+\+GLOBALS or DW\+\_\+\+GL\+\_\+\+PUBTYPES. Or call \doxylink{group__pubnames_ga10ffe6065920a9dca3f4e29deedce14b}{dwarf\+\_\+get\+\_\+pubtypes()}.

The following four were defined in SGI/\+\+IRIX compilers in the 1990s but were never part of the DWARF standard. These sections are accessed calling \doxylink{group__pubnames_gaef3a5b4e40f2f1e65c42eeff102733aa}{dwarf\+\_\+globals\+\_\+by\+\_\+type()} using type of DW\+\_\+\+GL\+\_\+\+FUNCS,DW\+\_\+\+GL\+\_\+\+TYPES,DW\+\_\+\+GL\+\_\+\+VARS, or DW\+\_\+\+GL\+\_\+\+WEAKS.

It not likely you will encounter these four sections.


\begin{DoxyCode}{0}
\DoxyCodeLine{.debug\_funcs}
\DoxyCodeLine{.debug\_typenames}
\DoxyCodeLine{.debug\_vars}
\DoxyCodeLine{.debug\_weaks}

\end{DoxyCode}
\hypertarget{index_dwsec_noobj}{}\doxysection{\texorpdfstring{Reading DWARF with no object file present}{Reading DWARF with no object file present}}\label{index_dwsec_noobj}
This most commonly happens with just-\/in-\/time compilation, and someone working on the code wants do debug this on-\/the-\/fly code in a situation where nothing can be written to disc, but DWARF can be constructed in memory.

For a simple example of this \begin{DoxySeeAlso}{See also}
\doxylink{group__jitreader}{Demonstrating reading DWARF without a file.}
\end{DoxySeeAlso}
But the {\itshape libdwarf} feature can be used in a wide variety of ways.

For example, the DWARF data could be kept in simple files of bytes on the internet. Or on the local net. Or if files can be written locally each section could be kept in a simple stream of bytes in the local file system.

Another example is a non-\/standard file system, or file format, with the intent of obfuscating the file or the DWARF.

For this to work the code generator must generate standard DWARF.

Overall the idea is a simple one:\+ You write a small handful of functions and supply function pointers and code implementing the functions. These are part of your application or library, not part of {\itshape libdwarf}.

You set up a little bit of data with that code (all described below) and then you have essentially written the dwarf\+\_\+init\+\_\+path equivalent and you can access compilation units, line tables etc and the standard {\itshape libdwarf} function calls work.

Take great care in your object reader code because any failure to reject object files with corrupt data in areas such as object headers, section headers, or relocation records nullifies the intended guarantee that the library will not crash.

Data you need to create involves these types. What follows describes how to fill them in and how to make them work for you.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{typedef}\ \textcolor{keyword}{struct\ }\doxymbox{\hyperlink{struct_dwarf___obj___access___interface__a__s}{Dwarf\_Obj\_Access\_Interface\_a\_s}}}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__allstructs_ga80e90b3f3f60f28d0098a1e0cd6cb371}{Dwarf\_Obj\_Access\_Interface\_a}};}
\DoxyCodeLine{\textcolor{keyword}{struct\ }\doxymbox{\hyperlink{struct_dwarf___obj___access___interface__a__s}{Dwarf\_Obj\_Access\_Interface\_a\_s}}\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{void}*\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ai\_object;}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{const}\ \doxymbox{\hyperlink{group__allstructs_ga35718824fe6de97511d7f34e452dccc3}{Dwarf\_Obj\_Access\_Methods\_a}}\ *ai\_methods;}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keyword}{typedef}\ \textcolor{keyword}{struct\ }\doxymbox{\hyperlink{struct_dwarf___obj___access___methods__a__s}{Dwarf\_Obj\_Access\_Methods\_a\_s}}}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__allstructs_ga35718824fe6de97511d7f34e452dccc3}{Dwarf\_Obj\_Access\_Methods\_a}}}
\DoxyCodeLine{struct\ \doxymbox{\hyperlink{struct_dwarf___obj___access___methods__a__s}{Dwarf\_Obj\_Access\_Methods\_a\_s}}\ \{}
\DoxyCodeLine{\ \ \ \ int\ \ \ \ (*om\_get\_section\_info)(\textcolor{keywordtype}{void}*\ obj,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ section\_index,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \doxymbox{\hyperlink{group__allstructs_ga99a5f45f60883d323df123b252139c79}{Dwarf\_Obj\_Access\_Section\_a}}*\ return\_section,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{keywordtype}{int}*\ error);}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga52e439e652a1a30277679f64f83cc0fe}{Dwarf\_Small}}\ \ \ \ \ \ (*om\_get\_byte\_order)(\textcolor{keywordtype}{void}*\ obj);}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga52e439e652a1a30277679f64f83cc0fe}{Dwarf\_Small}}\ \ \ \ \ \ (*om\_get\_length\_size)(\textcolor{keywordtype}{void}*\ obj);}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga52e439e652a1a30277679f64f83cc0fe}{Dwarf\_Small}}\ \ \ \ \ \ (*om\_get\_pointer\_size)(\textcolor{keywordtype}{void}*\ obj);}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ \ \ (*om\_get\_filesize)(\textcolor{keywordtype}{void}*\ obj);}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ \ \ (*om\_get\_section\_count)(\textcolor{keywordtype}{void}*\ obj);}
\DoxyCodeLine{\ \ \ \ int\ \ \ \ \ \ \ \ \ \ \ \ \ \ (*om\_load\_section)(\textcolor{keywordtype}{void}*\ obj,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ section\_index,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga52e439e652a1a30277679f64f83cc0fe}{Dwarf\_Small}}**\ return\_data,\ \textcolor{keywordtype}{int}*\ error);}
\DoxyCodeLine{\ \ \ \ int\ \ \ \ \ \ \ \ \ \ \ \ \ \ (*om\_relocate\_a\_section)(\textcolor{keywordtype}{void}*\ obj,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ section\_index,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\_Debug}}\ dbg,}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{keywordtype}{int}*\ error);}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keyword}{typedef}\ \textcolor{keyword}{struct\ }\doxymbox{\hyperlink{struct_dwarf___obj___access___section__a__s}{Dwarf\_Obj\_Access\_Section\_a\_s}}}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__allstructs_ga99a5f45f60883d323df123b252139c79}{Dwarf\_Obj\_Access\_Section\_a}}}
\DoxyCodeLine{struct\ \doxymbox{\hyperlink{struct_dwarf___obj___access___section__a__s}{Dwarf\_Obj\_Access\_Section\_a\_s}}\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{const}\ \textcolor{keywordtype}{char}*\ \ \ \ as\_name;}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ as\_type;}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ as\_flags;}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga16ddc0e584ea1a17237ccf1617f31075}{Dwarf\_Addr}}\ \ \ \ \ as\_addr;}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ as\_offset;}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ as\_size;}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ as\_link;}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ as\_info;}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ as\_addralign;}
\DoxyCodeLine{\ \ \ \ \doxymbox{\hyperlink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\_Unsigned}}\ as\_entrysize;}
\DoxyCodeLine{\};}

\end{DoxyCode}


{\bfseries{\doxylink{group__allstructs_ga99a5f45f60883d323df123b252139c79}{Dwarf\+\_\+\+Obj\+\_\+\+Access\+\_\+\+Section\+\_\+a}:\+}} Your implementation of a {\bfseries{om\+\_\+get\+\_\+section\+\_\+info}} must fill in a few fields for {\itshape libdwarf}. The fields here are standard Elf, but for most you can just use the value zero. We assume you will not be doing relocations at runtime and do not describe how to do relocations.

{\bfseries{as\+\_\+name:\+}} Here you set a section name via the pointer. The section names must be names as defined in the DWARF standard, so if such do not appear in your data you have to create the strings yourself.

{\bfseries{as\+\_\+type:\+}} Fill in zero.

{\bfseries{as\+\_\+flags:\+}} Fill in zero.

{\bfseries{as\+\_\+addr:\+}} Fill in the address, in local memory, where the bytes of the section are.

{\bfseries{as\+\_\+offset:\+}} Fill in zero.

{\bfseries{as\+\_\+size:\+}} Fill in the size, in bytes, of the section you are telling {\itshape libdwarf} about.

{\bfseries{as\+\_\+link:\+}} Fill in zero.

{\bfseries{as\+\_\+info:\+}} Fill in zero.

{\bfseries{as\+\_\+addralign:\+}} Fill in zero.

{\bfseries{as\+\_\+entrysize:\+}} Fill in one(1).

{\bfseries{\doxylink{struct_dwarf___obj___access___methods__a__s}{Dwarf\+\_\+\+Obj\+\_\+\+Access\+\_\+\+Methods\+\_\+a\+\_\+s}:\+}} The functions we need to access object data from {\itshape libdwarf} are declared here.

In these function pointer declarations \textquotesingle{}void \texorpdfstring{$\ast$}{*}obj\textquotesingle{} is intended to be a pointer (the object field in Dwarf\+\_\+\+Obj\+\_\+\+Access\+\_\+\+Interface\+\_\+s) that hides the library-\/specific and object-\/specific data that makes it possible to handle multiple object formats and multiple libraries. It is not required that one handles multiple such in a single {\itshape libdwarf} archive/\+shared-\/library (but not ruled out either). See dwarf\+\_\+elf\+\_\+object\+\_\+access\+\_\+internals\+\_\+t and dwarf\+\_\+elf\+\_\+access.\+c for an example.

Usually the struct {\bfseries{\doxylink{struct_dwarf___obj___access___methods__a__s}{Dwarf\+\_\+\+Obj\+\_\+\+Access\+\_\+\+Methods\+\_\+a\+\_\+s}}} is statically defined and the function pointers are set at compile time.

The om\+\_\+get\+\_\+filesize member is new September 4, 2021. Its position is NOT at the end of the list. The member names all now have om\+\_\+ prefix.\hypertarget{index_dwsec_sectiongroup}{}\doxysection{\texorpdfstring{Section Groups:\+ Split Dwarf, COMDAT groups}{Section Groups:\+ Split Dwarf, COMDAT groups}}\label{index_dwsec_sectiongroup}
A typical executable or shared object is unlikely to have any section groups as the linker would have removed those when building an executable or shared-\/object, and in that case what follows is irrelevant and unimportant.

{\bfseries{COMDAT}} groups are defined by the Elf ABI and enable compilers and linkers to work together to eliminate blocks of duplicate DWARF and duplicate CODE.

{\bfseries{Split}} {\bfseries{Dwarf}} (sometimes referred to as Debug Fission) allows compilers and linkers to separate large amounts of DWARF from the executable, shrinking disk space needed in the executable while allowing full debugging (also applies to shared objects).

See the DWARF5 Standard, Section E.\+1 Using Compilation Units page 364.

To name COMDAT groups (defined later here) we add the following defines to \doxylink{libdwarf_8h}{libdwarf.\+h} (the DWARF standard does not specify how to do any of this).


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{/*\ \ These\ support\ opening\ DWARF5\ split\ dwarf\ objects\ and}}
\DoxyCodeLine{\textcolor{comment}{\ \ \ \ Elf\ SHT\_GROUP\ blocks\ of\ DWARF\ sections.\ */}}
\DoxyCodeLine{\textcolor{preprocessor}{\#define\ DW\_GROUPNUMBER\_ANY\ \ 0}}
\DoxyCodeLine{\textcolor{preprocessor}{\#define\ DW\_GROUPNUMBER\_BASE\ 1}}
\DoxyCodeLine{\textcolor{preprocessor}{\#define\ DW\_GROUPNUMBER\_DWO\ \ 2}}

\end{DoxyCode}


The DW\+\_\+\+GROUPNUMBER\+\_\+ are used in {\itshape libdwarf} functions \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()}, \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()} and \doxylink{group__initfunctions_ga14c7d234b10005a8b2dfc320bbc775c9}{dwarf\+\_\+init\+\_\+b()}. In all those cases unless you know there is any complexity in your object file, pass in DW\+\_\+\+GROUPNUMBER\+\_\+\+ANY.

To see section groups usage, see the example source:\+ \begin{DoxySeeAlso}{See also}
\doxylink{group__showsecgroups}{A simple report on section groups.}

\doxylink{group__examplesecgroup}{Examining Section Group data}
\end{DoxySeeAlso}
The function interface declarations:\+

\begin{DoxySeeAlso}{See also}
\doxylink{group__secgroups_ga894bc7aaf5c3545cff97c4987c5b4570}{dwarf\+\_\+sec\+\_\+group\+\_\+sizes} 

\doxylink{group__secgroups_ga162abad83e103405607f7749792890fc}{dwarf\+\_\+sec\+\_\+group\+\_\+map}
\end{DoxySeeAlso}
If an object file has multiple groups {\itshape libdwarf} will not reveal contents of more than the single requested group with a given \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} call. One must pass in another groupnumber to another \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()}, meaning initialize a new \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug}, to get {\itshape libdwarf} to access that group.

When opening a \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} the following applies:\+

If DW\+\_\+\+GROUPNUMBER\+\_\+\+ANY is passed in {\itshape libdwarf} will choose either of DW\+\_\+\+GROUPNUMBER\+\_\+\+BASE(1) or DW\+\_\+\+GROUPNUMBER\+\_\+\+DWO (2) depending on the object content. If both groups one and two are in the object {\itshape libdwarf} will chose DW\+\_\+\+GROUPNUMBER\+\_\+\+BASE.

If DW\+\_\+\+GROUPNUMBER\+\_\+\+BASE is passed in {\itshape libdwarf} will choose it if non-\/split DWARF is in the object, else the init call will return DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY.

If DW\+\_\+\+GROUPNUMBER\+\_\+\+DWO is passed in {\itshape libdwarf} will choose it if .dwo sections are in the object, else the init will call return DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY.

If a groupnumber greater than two is passed in {\itshape libdwarf} accepts it, whether any sections corresponding to that groupnumber exist or not. If the groupnumber is not an actual group the init will call return DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY.

For information on groups "{}dwarfdump -\/i"{} on an object file will show all section group information {\bfseries{unless}} the object file is a simple standard object with no .dwo sections and no COMDAT groups (in which case the output will be silent on groups). Look for {\bfseries{ Section Groups data }} in the dwarfdump output. The groups information will be appearing very early in the dwarfdump output.

Sections that are part of an Elf COMDAT GROUP are assigned a group number \texorpdfstring{$>$}{>} 2. There can be many such COMDAT groups in an object file (but none in an executable or shared object). Each such COMDAT group will have a small set of sections in it and each section in such a group will be assigned the same group number by {\itshape libdwarf}.

Sections that are in a .dwp .dwo object file are assigned to DW\+\_\+\+GROUPNUMBER\+\_\+\+DWO,

Sections not part of a .dwp package file or a.\+dwo section, or a COMDAT group are assigned DW\+\_\+\+GROUPNUMBER\+\_\+\+BASE.

At least one compiler relies on relocations to identify COMDAT groups, but the compiler authors do not publicly document how this works so we ignore such (these COMDAT groups will result in {\itshape libdwarf} returning DW\+\_\+\+DLV\+\_\+\+ERROR).

Popular compilers and tools are using such sections. There is no detailed documentation that we can find (so far) on how the COMDAT section groups are used, so {\itshape libdwarf} is based on observations of what compilers generate.\hypertarget{index_dwsec_separatedebug}{}\doxysection{\texorpdfstring{Details on separate DWARF object access}{Details on separate DWARF object access}}\label{index_dwsec_separatedebug}
There are, at present, three distinct approaches in use to put DWARF information into separate objects to significantly shrink the size of the executable. All of them involve identifying a separate file.

Split Dwarf is one method. It defines the attribute {\bfseries{DW\+\_\+\+AT\+\_\+dwo\+\_\+name}} (if present) as having a file-\/system appropriate name of the split object with most of the DWARF.

The second is Macos d\+SYM. It is a convention of placing the DWARF-\/containing object (separate from the object containing code) in a specific subdirectory tree.

The third involves GNU debuglink and GNU debug\+\_\+id. These are two distinct ways (outside of DWARF) to provide names of alternative DWARF-\/containing objects elsewhere in a file system.

If one initializes a \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} object with \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} or \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()} appropriately {\itshape libdwarf} will automatically open the alternate d\+SYM or debuglink/\+debug\+\_\+id object on the object with most of the DWARF.

\begin{DoxySeeAlso}{See also}
\href{https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html}{\texttt{https:\+/\+/\+sourceware.\+org/\+gdb/\+onlinedocs/\+gdb/\+\+Separate-\/\+Debug-\/\+Files.\+html}}
\end{DoxySeeAlso}
{\itshape libdwarf} provides means to automatically read the alternate object (in place of the one named in the init call) or to suppress that and read the named object file.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ \doxymbox{\hyperlink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\_init\_path}}(\textcolor{keyword}{const}\ \textcolor{keywordtype}{char}\ *\ dw\_path,}
\DoxyCodeLine{\textcolor{keywordtype}{char}\ *\ \ \ \ \ \ \ \ \ \ \ \ dw\_true\_path\_out\_buffer,}
\DoxyCodeLine{\textcolor{keywordtype}{unsigned}\ \textcolor{keywordtype}{int}\ \ \ \ \ \ dw\_true\_path\_bufferlen,}
\DoxyCodeLine{\textcolor{keywordtype}{unsigned}\ \textcolor{keywordtype}{int}\ \ \ \ \ \ dw\_groupnumber,}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_ga6de1c2929cebfae36804315f7232cb19}{Dwarf\_Handler}}\ \ \ \ \ dw\_errhand,}
\DoxyCodeLine{\doxymbox{\hyperlink{group__basicdatatypes_ga376c1939313af42401fc67bc998fdd2c}{Dwarf\_Ptr}}\ \ \ \ \ \ \ \ \ dw\_errarg,}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\_Debug}}*\ \ \ \ \ \ dw\_dbg,}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\_Error}}*\ \ \ \ \ \ dw\_error);}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ \doxymbox{\hyperlink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\_init\_path\_dl}}(\textcolor{keyword}{const}\ \textcolor{keywordtype}{char}\ *dw\_path,}
\DoxyCodeLine{\textcolor{keywordtype}{char}\ \ \ \ \ \ \ \ \ \ \ \ *\ true\_path\_out\_buffer,}
\DoxyCodeLine{\textcolor{keywordtype}{unsigned}\ \ \ \ \ \ \ \ true\_path\_bufferlen,}
\DoxyCodeLine{\textcolor{keywordtype}{unsigned}\ \ \ \ \ \ \ \ groupnumber,}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_ga6de1c2929cebfae36804315f7232cb19}{Dwarf\_Handler}}\ \ \ errhand,}
\DoxyCodeLine{\doxymbox{\hyperlink{group__basicdatatypes_ga376c1939313af42401fc67bc998fdd2c}{Dwarf\_Ptr}}\ \ \ \ \ \ \ errarg,}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\_Debug}}\ \ \ \ \ *\ ret\_dbg,}
\DoxyCodeLine{\textcolor{keywordtype}{char}\ \ \ \ \ \ \ \ \ \ \ \ **\ dl\_path\_array,}
\DoxyCodeLine{\textcolor{keywordtype}{unsigned}\ \textcolor{keywordtype}{int}\ \ \ \ dl\_path\_count,}
\DoxyCodeLine{\textcolor{keywordtype}{unsigned}\ \textcolor{keywordtype}{char}\ \ \ *\ path\_source,}
\DoxyCodeLine{\doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\_Error}}\ \ \ \ \ *\ error);}

\end{DoxyCode}


Case 1:\+

If {\itshape dw\+\_\+true\+\_\+path\+\_\+out\+\_\+buffer} or {\itshape dw\+\_\+true\+\_\+path\+\_\+bufferlen} is passed in as zero then the library will not look for an alternative object.

Case 2:\+

If {\itshape dw\+\_\+true\+\_\+path\+\_\+out\+\_\+buffer} passes a pointer to space you provide and {\itshape dw\+\_\+true\+\_\+path\+\_\+bufferlen} passes in the length, in bytes, of the buffer, {\itshape libdwarf} will look for alternate DWARF-\/containing objects. We advise that the caller zero all the bytes in {\itshape dw\+\_\+true\+\_\+path\+\_\+out\+\_\+buffer} before calling.

If the alternate object name (with its null-\/terminator) is too long to fit in the buffer the call will return DW\+\_\+\+DLV\+\_\+\+ERROR with dw\+\_\+error providing error code DW\+\_\+\+DLE\+\_\+\+PATH\+\_\+\+SIZE\+\_\+\+TOO\+\_\+\+SMALL.

If the alternate object name fits in the buffer {\itshape libdwarf} will open and use that alternate file in the returned Dwarf\+\_\+\+Dbg.

It is up to callers to notice that {\itshape dw\+\_\+true\+\_\+path\+\_\+out\+\_\+buffer} now contains a string and callers will probably wish to do something with the string.

If the initial byte of {\itshape dw\+\_\+true\+\_\+path\+\_\+out\+\_\+buffer} is a non-\/null when the call returns then an alternative object was found and opened.

The second function, \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()}, is the same as \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} except the \+\_\+dl version has three additional arguments, as follows:\+

Pass in NULL or {\itshape dw\+\_\+dl\+\_\+path\+\_\+array}, an array of pointers to strings with alternate GNU debuglink paths you want searched. For most people, passing in NULL suffices.

Pass in {\itshape dw\+\_\+dl\+\_\+path\+\_\+array\+\_\+size}, the number of elements in {\itshape dw\+\_\+dl\+\_\+path\+\_\+array}.

Pass in {\itshape dw\+\_\+dl\+\_\+path\+\_\+source} as NULL or a pointer to char. If non-\/null {\itshape libdwarf} will set it to one of three values:\+


\begin{DoxyItemize}
\item DW\+\_\+\+PATHSOURCE\+\_\+basic which means the original input {\itshape dw\+\_\+path} is the one opened in dw\+\_\+dbg.
\item DW\+\_\+\+PATHSOURCE\+\_\+dsym which means a Macos d\+SYM object was found and is the one opened in dw\+\_\+dbg. {\itshape dw\+\_\+true\+\_\+path\+\_\+out\+\_\+buffer} contains the d\+SYM object path.
\item DW\+\_\+\+PATHSOURCE\+\_\+debuglink which means a GNU debuglink or GNU debug-\/id path was found and names the one opened in dw\+\_\+dbg. {\itshape dw\+\_\+true\+\_\+path\+\_\+out\+\_\+buffer} contains the object path.
\end{DoxyItemize}\hypertarget{index_dwsec_shared}{}\doxysection{\texorpdfstring{Linking against libdwarf.\+so (or dll or dylib)}{Linking against libdwarf.\+so (or dll or dylib)}}\label{index_dwsec_shared}
If you wish to do the basic {\itshape libdwarf} tests and are linking against a shared library {\itshape libdwarf} you must do an install for the tests to succeed (in some environments it is not strictly necessary).

For example, if building with configure, do 
\begin{DoxyCode}{0}
\DoxyCodeLine{make}
\DoxyCodeLine{make\ install}
\DoxyCodeLine{make\ check}

\end{DoxyCode}


You can install anywhere, there is no need to install in a system directory! Creating a temporary directory and installing there suffices. If installed in appropriate system directories that works too.

When compiling to link against a shared library {\itshape libdwarf} you {\bfseries{must not define LIBDWARF\+\_\+\+STATIC}}.

For examples of this for all three build systems read the project shell script 
\begin{DoxyCode}{0}
\DoxyCodeLine{scripts/allsimplebuilds.sh}

\end{DoxyCode}
\hypertarget{index_dwsec_static}{}\doxysection{\texorpdfstring{Linking against libdwarf.\+a}{Linking against libdwarf.\+a}}\label{index_dwsec_static}

\begin{DoxyItemize}
\item If you are building an application
\item And are linking your application against a static library libdwarf.\+a
\item Then you must ensure that each source file compilation with an include of \doxylink{libdwarf_8h}{libdwarf.\+h} has the macro {\bfseries{LIBDWARF\+\_\+\+STATIC}} defined to your source compilation.
\item If {\itshape libdwarf} was built with zlib and zstd decompression library enabled you must add -\/lz -\/lzstd to the link line of the build of your application.
\end{DoxyItemize}

To pass {\bfseries{LIBDWARF\+\_\+\+STATIC}} to the preprocessor with Visual Studio:\+


\begin{DoxyItemize}
\item Right click on a project name
\item In the contextual menu, click on {\bfseries{Properties}} at the very bottom.
\item In the new window, double click on {\bfseries{C/\+\+C++}}
\item On the right, click on {\bfseries{Preprocessor definitions}}
\item There is a small down arrow on the right, click on it then click on {\bfseries{Modify}}
\item Add {\bfseries{LIBDWARF\+\_\+\+STATIC}} to the values
\item Click on {\bfseries{OK}} to close the windows
\end{DoxyItemize}\hypertarget{index_dwsec_dbglink}{}\doxysection{\texorpdfstring{Suppressing CRC calculation for debuglink}{Suppressing CRC calculation for debuglink}}\label{index_dwsec_dbglink}
GNU Debuglink-\/specific issue:\+

If GNU debuglink is present and considered by \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} or \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()} the library may be required to compute a 32bit crc (Cyclic Redundancy Check) on the file found via GNU debuglink.

\begin{DoxySeeAlso}{See also}
\href{https://en.wikipedia.org/wiki/Cyclic_redundancy_check}{\texttt{https:\+/\+/\+en.\+wikipedia.\+org/\+wiki/\+\+Cyclic\+\_\+redundancy\+\_\+check}}
\end{DoxySeeAlso}
For people doing repeated builds of objects using such the crc check is a waste of time as they know the crc comparison will pass.

For such situations a special interface function lets the \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} or \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()} caller suppress the crc check without having any effect on anything else in {\itshape libdwarf}.

It might be used as follows (the same pattern applies to \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()} ) for any program that might do multiple \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} or \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()} calls in a single program execution.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ res\ \ \ \ \ \ =\ 0;}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ crc\_check=\ 0;}
\DoxyCodeLine{}
\DoxyCodeLine{crc\_check\ =\ \doxymbox{\hyperlink{group__gnudebuglink_gae02f80e472417deef078a26c2cafe903}{dwarf\_suppress\_debuglink\_crc}}(1);}
\DoxyCodeLine{res\ =\ \doxymbox{\hyperlink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\_init\_path}}(..usual\ arguments);}
\DoxyCodeLine{\textcolor{comment}{/*\ \ Reset\ the\ crc\ flag\ to\ previous\ value.\ */}}
\DoxyCodeLine{\doxymbox{\hyperlink{group__gnudebuglink_gae02f80e472417deef078a26c2cafe903}{dwarf\_suppress\_debuglink\_crc}}(crc\_check);}
\DoxyCodeLine{\textcolor{comment}{/*\ \ Now\ check\ res\ in\ the\ usual\ way.\ */}}

\end{DoxyCode}


This pattern ensures the crc check is suppressed for this single \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} or \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()} call while leaving the setting unchanged for further \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} or \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()} calls in the running program.\hypertarget{index_userobjread}{}\doxysection{\texorpdfstring{Object Reading By User Code}{Object Reading By User Code}}\label{index_userobjread}
With the usual libdwarf initialization functions the library does extensive checks of object formats and attempts to find all object errors and returns error codes reading objects with errors affecting the library. Including, for example, object header errors and relocation section errors. The intent is to return correct output for correct DWARF and avoid program crashes in the library when the object or DWARF data is corrupt (returning error codes as appropriate).

\doxylink{group__initfunctions_ga44350f3d6a177c86332cdbb30fa78d9e}{dwarf\+\_\+object\+\_\+init\+\_\+b()} is an alternative to the usual libdwarf initialization functions -- making it possible to read object formats libdwarf knows nothing about. This interface delegates the object reading to user code.

\doxylink{group__initfunctions_ga44350f3d6a177c86332cdbb30fa78d9e}{dwarf\+\_\+object\+\_\+init\+\_\+b()} requires the user code to provide correct and complete section information for the sections the library requires. The library cannot guarantee correct, successful, crash-\/free operation if the user code reading an object is insufficiently careful, thorough, and consistent in returning DW\+\_\+\+DLV\+\_\+\+OK, DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY, and DW\+\_\+\+DLV\+\_\+\+ERROR as applicable.\hypertarget{index_dwsec_mmap}{}\doxysection{\texorpdfstring{dwsec\+\_\+mmap}{dwsec\+\_\+mmap}}\label{index_dwsec_mmap}
As of version 0.\+12.\+0 libdwarf allows callers to select mmap (instead of malloc/\+read) to access object section DWARF data. Even if mmap is selected it is possible libdwarf will chose to use malloc in specific cases.

If at library build time the required functions/\+header are not available the following will have no effect.

One way to select mmap is to call


\begin{DoxyCode}{0}
\DoxyCodeLine{\doxymbox{\hyperlink{group__sectionallocpref_ga38895d41776523190f5c7e2af4f6391c}{dwarf\_set\_load\_preference}}(Dwarf\_Alloc\_Mmap);}

\end{DoxyCode}


Another way to select mmap is with an environment variable


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{export}\ DWARF\_WHICH\_ALLOC=mmap}

\end{DoxyCode}


so libdwarf will see the variable at runtime.

The environment variable overrides the function call. ~\newline


Calling dwarf\+\_\+set\+\_\+load\+\_\+preference(0) will return the current overall preference will return the current overall preference, an instance of


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{enum}\ \doxymbox{\hyperlink{group__allstructs_ga8e19573b56799157d063d8cc2828f69b}{Dwarf\_Sec\_Alloc\_Pref}}\ \ }

\end{DoxyCode}


The new function ~\newline



\begin{DoxyCode}{0}
\DoxyCodeLine{\doxymbox{\hyperlink{group__sectionallocpref_ga00887b728c214e4d85d50ac0d0d1f9dd}{dwarf\_get\_mmap\_count}}(\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\_Debug}}\ dw\_dbg)}

\end{DoxyCode}


returns the application count and size of allocations for DWARF sections from the open \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} pointer.

Each supported build environment has a new build option to prevent libdwarf from assuming that things in the build are always present.\hypertarget{index_dwsec_changes}{}\doxysection{\texorpdfstring{Recent Changes}{Recent Changes}}\label{index_dwsec_changes}
We list these with newest first.

{\bfseries{Changes 2.\+3.\+0 to 2.\+3.\+1}}

Fixed vulnerability oss fuzz 4475563464 (aka libdwarf DW202602-\/001) reading frame data from a fuzzed (corrupted) DWARF frame section. \begin{DoxySeeAlso}{See also}
\href{https://www.prevanders.net/dwarfbug.html}{\texttt{https:\+/\+/\+www.\+prevanders.\+net/\+dwarfbug.\+html}} DW202602-\/001 or the text file bugxml/\+data.\+txt in the source release.
\end{DoxySeeAlso}
Now allows DW\+\_\+\+AT\+\_\+dwo\+\_\+id and DW\+\_\+\+AT\+\_\+\+GNU\+\_\+dwo\+\_\+id in any DWARF4 or DWARF5 object where such an attribute makes sense.

Now allows access to a .eh\+\_\+frame section (APPLE names it \+\_\+\+\_\+eh\+\_\+frame) in a Mach-\/o executable. Just call \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} (for example) and ensure the dw\+\_\+true\+\_\+path\+\_\+out\+\_\+buffer and dw\+\_\+true\+\_\+path\+\_\+bufferlen arguments are passed in as zero (0). Corrects a sanity check of Mach-\/o objects by eliminating an inappropriate multiply of the sizeofcmds header field.

{\bfseries{Changes 2.\+2.\+0 to 2.\+3.\+0}}

Released 1 February 2026

Added function \doxylink{group__frame_gad939575875a940728b8f13fcc592fe4c}{dwarf\+\_\+iterate\+\_\+fde\+\_\+all\+\_\+regs3()} which lets callers get all rows of the .debug\+\_\+frame and .eh\+\_\+frame sections via callbacks the function makes to a function you write. Simple to use and, for FDEs with many rows, sixty times faster. A prerelease version failed to allow retrieving the CFA pseudo-\/register value, but that is fixed. See dwarfexample/\+frame2.\+c for an example of use.

Added function \doxylink{group__harmless_ga07bb6b4aba797e93aeaf22d543a46b66}{dwarf\+\_\+set\+\_\+harmless\+\_\+errors\+\_\+enabled( \+Dwarf\+\_\+\+Debug dw\+\_\+dbg,int dw\+\_\+v)}. Passing in dw\+\_\+v of 0 (zero) turns off checking for what are really harmless errors, which makes a meaningful improvement in library performance for some calls. By default harmless errors are checked-\/for.

\doxylink{group__frame_gae32b7cb9b94a3f865d5a4c426b4ff148}{dwarf\+\_\+set\+\_\+frame\+\_\+rule\+\_\+table\+\_\+size()} now allows setting register rules table size as low as 50 entries. The default remains arbitrary:\+ DW\+\_\+\+FRAME\+\_\+\+LAST\+\_\+\+REG\+\_\+\+NUM (189) as that suffices for most architectures without being excessive.

{\bfseries{Changes 2.\+1.\+0 to 2.\+2.\+0}}

Released 10 October 2025

Added functions \doxylink{group__dieentry_gaf312e176aa3ece6745d67d25c28187ca}{dwarf\+\_\+lvn\+\_\+name\+\_\+direct()} \doxylink{group__dieentry_gaee81d47941c654d2db072cc6fbf991d4}{dwarf\+\_\+lvn\+\_\+name()} \doxylink{group__dieentry_gaa129c951d05816d87923691dec41d596}{dwarf\+\_\+lvn\+\_\+table\+\_\+entry()} enabling access to all the fields relevant in DWARF6 DW\+\_\+\+AT\+\_\+language\+\_\+version attributes.

In builds using (for example) cc -\/std=c99 gcc will turn off visibility of strdup() in string.\+h leading to a build failure. So now we define \+\_\+\+GNU\+\_\+\+SOURCE in builds.

Corrected a bug in reading line table data that used DW\+\_\+\+FORM\+\_\+strx (and other strx forms).

Fixed various failures to handle corrupted (fuzzed) Apple Mach-\/o object files.

{\bfseries{Changes 2.\+0.\+0 to 2.\+1.\+0}}

Released 20 July 2025

Corrected (and tested) use of DWARF6 attributes DW\+\_\+\+AT\+\_\+language\+\_\+name and DW\+\_\+\+AT\+\_\+language\+\_\+version. As of July 2025 we are not aware of a released compiler providing these attributes.

Added function \doxylink{group__dieentry_gac50aedfe9f0c90b97cec050aa1a05856}{dwarf\+\_\+srclanglname()} so that DW\+\_\+\+AT\+\_\+language\+\_\+name attribute values can be accessed. Added \doxylink{group__dieentry_gaad36cd3bf1e3a537bdfcf74d6b78e7fb}{dwarf\+\_\+language\+\_\+version\+\_\+data()} because \doxylink{group__dieentry_gabc062f02a8fbc4eb8cfa2e6ab8f576ed}{dwarf\+\_\+language\+\_\+version\+\_\+string()} is not an appropriate function name here. The old name still exists and works.

Added \doxylink{group__dieentry_ga8e2f3cd2631f1f8b786acdb0a4cf8434}{dwarf\+\_\+srclanglname\+\_\+version()} so that the data provided in DWARF6 DW\+\_\+\+AT\+\_\+language\+\_\+version can be returned. ~\newline


Fixed minor warnings from a compiler (dwarfgen) and from meson. No change to output.

Removed heuristic checks for decompress reasonableness as such proved to be ... unreasonable in certain real object files..

Corrected the cmake build of shared-\/library libdwarfp/\+\+CMake\+Lists.\+txt

Given an unusual object using debuglink but with no sections with names starting with .debug\+\_\+ or \+\_\+eh\+\_\+frame, libdwarf would complain about not having any DWARF sections and ignore the debuglink data. See github issue 297 for details of the fix.

{\bfseries{Changes 0.\+12.\+0 to 2.\+0.\+0}}

Released 20 May 2025.

Skipping all versions 1.\+x.\+x because before libdwarf used Semantic Versioning gcc built libdwarf.\+so.\+1.\+0.\+0 .

Fixed a longstanding bug in configure.\+ac which began to cause builds to fail with recent autoconf.

Fixed a problem in test/\+\+Cmake\+Lists.\+txt that caused current builds to fail on Msys2 Mingw64. Had been working for many months.

Updated the error report (for zlib, zstd) when decompression exceeds a heuristic. Now reports the compressed-\/len and the uncompressed-\/len. Increased the heuristic multiple allowed from 16 to 32.

{\bfseries{Changes 0.\+11.\+1 to 0.\+12.\+0}}

Released 02 April 2025

To optionally support mmap/\+munmap of object files sections we read we have added a function prototype for struct \doxylink{struct_dwarf___obj___access___methods__a__s}{Dwarf\+\_\+\+Obj\+\_\+\+Access\+\_\+\+Methods\+\_\+a\+\_\+s} function om\+\_\+load\+\_\+section(). This will help when reading multi-\/gigabyte object files. And we added a function prototype for destructing the object specific data while removing library internal public functions.

If an application does not call any of the functions which are new in v0.\+12.\+0 then it will work without recompilation.

Any application calling the new functions (for example, v0.\+12.\+0 dwarfdump) will only work with a v0.\+12.\+0 libdwarf.

If one is calling \doxylink{group__initfunctions_ga44350f3d6a177c86332cdbb30fa78d9e}{dwarf\+\_\+object\+\_\+init\+\_\+b()} (almost no one ever calls this function) one is therefore instantiating struct \doxylink{struct_dwarf___obj___access___methods__a__s}{Dwarf\+\_\+\+Obj\+\_\+\+Access\+\_\+\+Methods\+\_\+a\+\_\+s} oneself, you will surely find that your application will not work with libdwarf 0.\+12.\+0. Moreover, recompilation will fail unless you update your source to add the two new pointers to your instantiation (typically just add two zeros or NULLs in that struct instance).

Added new API function \doxylink{group__objectsections_ga5eed38d462227f6573215263319adcae}{dwarf\+\_\+machine\+\_\+architecture\+\_\+a()} which has an additional argument added to let dwarfdump create an better .text (etc) address-\/range for the object file being read for improved checking (fewer incorrect error reports) in dwarfdump -\/k output.

Up through December 2024 libdwarf could be made to be very very slow (Denial of Service) with calls with thousands of duplicate attributes in an abbreviation list of a specially constructed Compilation Unit.

Beginning 2025 by default that cannot happen as the library quickly notices and returns DW\+\_\+\+DLV\+\_\+\+ERROR with error details noted. Callers should check the return value and act appropriately, as always, when calling the library.

In case one has (and cannot fix) object files with duplicated attributes one can call a new API function:\+ \doxylink{group__miscellaneous_gabc31b8456210a8f8fd3770365212c744}{dwarf\+\_\+library\+\_\+allow\+\_\+dup\+\_\+attr()}. The library defaults to false (0) meaning the checks are done in libdwarf by default. Pass non-\/zero value to allow duplicate attributes in a Debugging Information Entry through to callers.

Added the ability to select, at runtime, whether libdwarf will use malloc to load section content from an object file being read (previously the only option) or will use mmap instead. ~\newline
 If the build determines mmap is unavailable then malloc will be used.

Added API function \doxylink{group__sectionallocpref_ga38895d41776523190f5c7e2af4f6391c}{dwarf\+\_\+set\+\_\+load\+\_\+preference()} giving callers the option to choose the default section load functions. libdwarf now recognizes the environment variable DWARF\+\_\+\+WHICH\+\_\+\+ALLOC to select whether the library uses mmap or malloc/\+read to load object section data, and the environment variable values \textquotesingle{}DWARF\+\_\+\+WHICH\+\_\+\+ALLOC=mmap\textquotesingle{} or \textquotesingle{}DWARF\+\_\+\+WHICH\+\_\+\+ALLOC=malloc\textquotesingle{} are the only values recognized. A recognized environment variable overrides \doxylink{group__sectionallocpref_ga38895d41776523190f5c7e2af4f6391c}{dwarf\+\_\+set\+\_\+load\+\_\+preference()} values. If the libdwarf build determines mmap is unavailable then only malloc will be used.

Added API function \doxylink{group__sectionallocpref_ga00887b728c214e4d85d50ac0d0d1f9dd}{dwarf\+\_\+get\+\_\+mmap\+\_\+count()} giving callers the ability to determine what section loads were used and the total amount of section data loaded.

Added API function dwarf\+\_\+get\+\_\+\+LANGUAGE\+\_\+name() to be able to easily get a string for DW\+\_\+\+LNAME\+\_\+\+Ada etc.

Added API function \doxylink{group__dieentry_gabc062f02a8fbc4eb8cfa2e6ab8f576ed}{dwarf\+\_\+language\+\_\+version\+\_\+string()}. This returns information defined by DWARF 6 and useful in interpreting DWARF6 language-\/version strings based on a name accessed from DW\+\_\+\+AT\+\_\+language\+\_\+name attribute.

{\bfseries{Changes 0.\+11.\+0 to 0.\+11.\+1}}

Corrected handling of DWARF5 .debug\+\_\+rnglists and .debug\+\_\+loclists. No API change, no incompatibilities.

{\bfseries{Changes 0.\+10.\+1 to 0.\+11.\+0}}

Added function \doxylink{group__ranges_ga59888eaf32d05ee39556fe7e271a3baf}{dwarf\+\_\+get\+\_\+ranges\+\_\+baseaddress()} to the api to allow dwarfdump and other library callers to easily derive the (cooked) address from the raw data in the DWARF2, DWARF3, DWARF4 .debug\+\_\+ranges section. An example of use is in \doxylink{checkexamples_8c}{doc/\+checkexamples.\+c} (see examplev).

{\bfseries{Changes 0.\+9.\+2 to 0.\+10.\+1}}

Released 01 July 2024 (Release 0.\+10.\+0 was missing a CMake\+Lists.\+txt file and is withdrawn).

Added API function \doxylink{group__locations_ga8b3ebddae8d5dc0f617ce87e3eb4133f}{dwarf\+\_\+get\+\_\+locdesc\+\_\+entry\+\_\+e()} to allow dwarfdump to report some data from .debug\+\_\+loclists more completely -- it reports a byte length of each loclist item. This is of little interest to anyone, surely. \doxylink{group__locations_ga889f24f93fe1ff22a64772fd42baf822}{dwarf\+\_\+get\+\_\+locdesc\+\_\+entry\+\_\+d()} is still what you should be using.

\doxylink{group__debugaddr_gae91d85a860a4dd8e25ab2e9d90810ee0}{dwarf\+\_\+debug\+\_\+addr\+\_\+table()} now supports reading the DWARF4 GNU extension .debug\+\_\+addr table.

A heuristic sanity check for PE object files was too conservative in limiting Virtual\+Size to 200MB. A library user has an exe with .debug\+\_\+info size of over 200MB. Increased the limit to be 2000MB and changed the names of the errors for the three heuristic checks to include {\itshape HEURISTIC} so it is easier to know the kind of error/\+failure it is.

When doing a shared-\/library build with cmake we were not emitting the correct .so version names nor setting SONAME with the correct version name. This long-\/standing mistake is now fixed.

{\bfseries{Changes 0.\+9.\+1 to 0.\+9.\+2}}

Version 0.\+9.\+2 released 2 April 2024

Vulnerabilities DW202402-\/001, DW202402-\/002,DW202402-\/003, and DW202403-\/001 could crash {\itshape libdwarf} given a carefully corrupted (fuzzed) DWARF object file. Now the library returns an error for these corruptions. DW\+\_\+\+CFA\+\_\+high\+\_\+user (in \doxylink{dwarf_8h}{dwarf.\+h}) was a misspelling. Added the correct spelling DW\+\_\+\+CFA\+\_\+hi\+\_\+user and a comment on the incorrect spelling.

{\bfseries{Changes 0.\+9.\+0 to 0.\+9.\+1}}

Version 0.\+9.\+1 released 27 January 2024

The abbreviation code type returned by \doxylink{group__dieentry_ga861265a03e05be9dd2e20a5016891938}{dwarf\+\_\+die\+\_\+abbrev\+\_\+code()} changed from {\bfseries{int}} to {\bfseries{\doxylink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\+\_\+\+Unsigned}}} as abbrev codes are not constrained by the DWARF Standard.

The section count returned by \doxylink{group__objectsections_ga7948c70bf9dff86a1143d314f45f9e98}{dwarf\+\_\+get\+\_\+section\+\_\+count()} is now of type {\bfseries{\doxylink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\+\_\+\+Unsigned}}}. The previous type of {\bfseries{int}} never made sense in {\itshape libdwarf}. Callers will, in practice, see the same value as before.

All type-\/warnings issued by MSVC have been fixed.

Problems reading Macho (Apple) relocatable object files have been fixed.

Each of the build systems available now has an option which eliminates {\itshape libdwarf} references to the object section decompression libraries. See the respective READMEs.

{\bfseries{Changes 0.\+8.\+0 to 0.\+9.\+0}}

Version 0.\+9.\+0 released 8 December 2023

Adding functions (rarely needed) for callers with special requirements. Added \doxylink{group__objectsections_gaa195322a359b88aaf2b97b58d58ddc68}{dwarf\+\_\+get\+\_\+section\+\_\+info\+\_\+by\+\_\+name\+\_\+a()} and \doxylink{group__objectsections_ga3d5a637aa6ed1cd81be2019f4cf6a445}{dwarf\+\_\+get\+\_\+section\+\_\+info\+\_\+by\+\_\+index\+\_\+a()} which add dw\+\_\+section\+\_\+flags pointer argument to return the object section file flags (whose meaning depends entirely on the object file format), and dw\+\_\+section\+\_\+offset pointer argument to return the object-\/relevant offset of the section (here too the meaning depends on the object format). Also added \doxylink{group__objectsections_ga550018e3e6062516d4b6be837008a55f}{dwarf\+\_\+machine\+\_\+architecture()} which returns a few top level data items about the object {\itshape libdwarf} has opened, including the \textquotesingle{}machine\textquotesingle{} and \textquotesingle{}flags\textquotesingle{} from object headers (all supported object types).

This adds new library functions \doxylink{group__compilationunit_ga282a397fc2095bd2939d486b232e3cc2}{dwarf\+\_\+next\+\_\+cu\+\_\+header\+\_\+e()} and \doxylink{group__compilationunit_gac9755be1dca4cc32c3a477d1f10f35f4}{dwarf\+\_\+siblingof\+\_\+c()}. Used exactly as documented \doxylink{group__compilationunit_ga474f73416ef468aab00dffbbdd149b0e}{dwarf\+\_\+next\+\_\+cu\+\_\+header\+\_\+d()} and \doxylink{group__compilationunit_gab8ae0bd010de9b7dca65f761b2c395e1}{dwarf\+\_\+siblingof\+\_\+b()} work fine and continue to be supported for the forseeable future. However it would be easy to misuse as the requirement that \doxylink{group__compilationunit_gab8ae0bd010de9b7dca65f761b2c395e1}{dwarf\+\_\+siblingof\+\_\+b()} be called immediately after a successful call to \doxylink{group__compilationunit_ga474f73416ef468aab00dffbbdd149b0e}{dwarf\+\_\+next\+\_\+cu\+\_\+header\+\_\+d()} was never stated and that dependency was impossible to enforce. The dependency was an API mistake made in 1992.

So \doxylink{group__compilationunit_ga282a397fc2095bd2939d486b232e3cc2}{dwarf\+\_\+next\+\_\+cu\+\_\+header\+\_\+e()} now returns the compilation-\/unit DIE as well as header data and \doxylink{group__compilationunit_gac9755be1dca4cc32c3a477d1f10f35f4}{dwarf\+\_\+siblingof\+\_\+c()} is not needed except to traverse sibling DIEs. (the compilation-\/unit DIE by definition has no siblings).

Changes were required to support Mach-\/O (Apple) universal binaries, which were not readable by earlier versions of the library.

We have new library functions \doxylink{group__initfunctions_gac46672bc652e351ce33e6ac53dfa18c3}{dwarf\+\_\+init\+\_\+path\+\_\+a()}, \doxylink{group__initfunctions_ga62b9292c851fd242e18f9716c1d6e3b8}{dwarf\+\_\+init\+\_\+path\+\_\+dl\+\_\+a()}, and \doxylink{group__miscellaneous_ga51dd900af8bbc3dcec87abf0887b6e68}{dwarf\+\_\+get\+\_\+universalbinary\+\_\+count()}.

The first two allow a caller to specify which (numbering from zero) object file to report on by adding a new argument dw\+\_\+universalnumber. Passing zero as the dw\+\_\+universalnumber argument is always safe.

The third lets callers retrieve the number being used.

These new calls do not replace anything so existing code will work fine.

Applying the previously existing calls \doxylink{group__initfunctions_ga8970fc7d21c9bfe1e7b33fe86579dd3d}{dwarf\+\_\+init\+\_\+path()} \doxylink{group__initfunctions_ga8f0107a24ee3013be3f4853295800ff4}{dwarf\+\_\+init\+\_\+path\+\_\+dl()} to a Mach-\/O universal binary works, but the library will return data on the first (index zero) as a default since there is no dw\+\_\+universalnumber argument possible.

For improved performance in reading Fde data when iterating though all usable pc values we add \doxylink{group__frame_gad02f3b78d6cebb9e60c1b00dadd2ecb8}{dwarf\+\_\+get\+\_\+fde\+\_\+info\+\_\+for\+\_\+all\+\_\+regs3\+\_\+b()}, which returns the next pc value with actual frame data. We retain \doxylink{group__frame_gaa8ed0eaa63677b844d57a3910595b5f5}{dwarf\+\_\+get\+\_\+fde\+\_\+info\+\_\+for\+\_\+all\+\_\+regs3()} so existing code need not change.

{\bfseries{Changes 0.\+7.\+0 to 0.\+8.\+0}}

v0.\+8.\+0 released 2023-\/09-\/20

New functions \doxylink{group__frame_ga07ff07a2380089af1a10b43592a69850}{dwarf\+\_\+get\+\_\+fde\+\_\+info\+\_\+for\+\_\+reg3\+\_\+c()}, \doxylink{group__frame_gad61d9e9b0724b08706e607d4d37fa5a0}{dwarf\+\_\+get\+\_\+fde\+\_\+info\+\_\+for\+\_\+cfa\+\_\+reg3\+\_\+c()} are defined. The advantage of the new versions is they correctly type the dw\+\_\+offset argument return value as \doxylink{group__basicdatatypes_gac91d9490d58c8d86a4d5b63ca93ba6dd}{Dwarf\+\_\+\+Signed} instead of the earlier and incorrect type \doxylink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\+\_\+\+Unsigned}.

The original functions \doxylink{group__frame_gafb0eedbffa619e2bce6e454d956b6ccc}{dwarf\+\_\+get\+\_\+fde\+\_\+info\+\_\+for\+\_\+reg3\+\_\+b()} and \doxylink{group__frame_ga294a626cd6b89ce9ad020f4e3929f630}{dwarf\+\_\+get\+\_\+fde\+\_\+info\+\_\+for\+\_\+cfa\+\_\+reg3\+\_\+b()} continue to exist and work for compatibility with the previous release.

For all open() calls for which the O\+\_\+\+CLOEXEC flag exists we now add that flag to the open() call.

Vulnerabilities involving reading corrupt object files (created by fuzzing) have been fixed:\+ DW202308-\/001 (ossfuzz 59576), DW202307-\/001 (ossfuzz 60506), DW202306-\/011 (ossfuzz 59950), DW202306-\/009 (ossfuzz 59755), DW202306-\/006 (ossfuzz 59727), DW202306-\/005 (ossfuzz 59717), DW202306-\/004 (ossfuzz 59695), DW202306-\/002 (ossfuzz 59519), DW202306-\/001 (ossfuzz 59597). DW202305-\/010 (ossfuzz 59478). DW202305-\/009 (ossfuzz 56451). DW202305-\/008 (ossfuzz 56451), DW202305-\/007 (ossfuzz 56474), DW202305-\/006 (ossfuzz 56472), DW202305-\/005 (ossfuzz 56462), DW202305-\/004 (ossfuzz 56446).

{\bfseries{Changes 0.\+6.\+0 to 0.\+7.\+0}}

v0.\+7.\+0 released 2023-\/05-\/20

Elf section counts can exceed 16 bits (on linux see {\bfseries{man 5 elf}}) so some function prototype members of struct {\bfseries{\doxylink{struct_dwarf___obj___access___methods__a__s}{Dwarf\+\_\+\+Obj\+\_\+\+Access\+\_\+\+Methods\+\_\+a\+\_\+s}}} changed. Specifically, om\+\_\+get\+\_\+section\+\_\+info() om\+\_\+load\+\_\+section(), and om\+\_\+relocate\+\_\+a\+\_\+section() now pass section indexes as \doxylink{group__basicdatatypes_ga5de64bb9627534a24dcbccc327916265}{Dwarf\+\_\+\+Unsigned} instead of \doxylink{group__basicdatatypes_ga4fb2b14ce7a6d27321fa7999b46b82bd}{Dwarf\+\_\+\+Half}. Without this change executables/\+objects with more than 64K sections cannot be read by {\itshape libdwarf}. This is unlikely to affect your code since for most users {\itshape libdwarf} takes care of this and dwarfdump is aware of this change.

Two functions have been removed from \doxylink{libdwarf_8h}{libdwarf.\+h} and the library:\+ dwarf\+\_\+dnames\+\_\+abbrev\+\_\+by\+\_\+code() and dwarf\+\_\+dnames\+\_\+abbrev\+\_\+form\+\_\+by\+\_\+index().

dwarf\+\_\+dnames\+\_\+abbrev\+\_\+by\+\_\+code() is slow and pointless. Use either \doxylink{group__debugnames_gadfb161993f617a4a233583ec5745de6a}{dwarf\+\_\+dnames\+\_\+name()} or \doxylink{group__debugnames_gac2da249bb89c9fb3ed870c9e57bb68a6}{dwarf\+\_\+dnames\+\_\+abbrevtable()} instead, depending on what you want to accomplish.

dwarf\+\_\+dnames\+\_\+abbrev\+\_\+form\+\_\+by\+\_\+index() is not needed, was difficult to call due to argument list requirements, and never worked.

{\bfseries{Changes 0.\+5.\+0 to 0.\+6.\+0}}

v0.\+6.\+0 released 2023-\/02-\/20 The dealloc required by \doxylink{group__dieentry_gab96a88bce3ff3a447eb7266f1b66cc10}{dwarf\+\_\+offset\+\_\+list()} was wrong. The call could crash {\itshape libdwarf} on systems with 32bit pointers. The new and proper dealloc (for all pointer sizes) is dwarf\+\_\+dealloc(dbg,offsetlistptr,\+DW\+\_\+\+DLA\+\_\+\+UARRAY);

A memory leak from \doxylink{group__locations_gadb9d0258969de3bccd1a905840ca7256}{dwarf\+\_\+load\+\_\+loclists()} and \doxylink{group__rnglists_gabc0a00e60b297ce23148267fe8436509}{dwarf\+\_\+load\+\_\+rnglists()} is fixed and the libdwarf-\/regressiontests error that hid the leak has also been fixed.

A {\bfseries{compatibility}} change affects callers of \doxylink{group__dieentry_gad772c3700fc2cdb8d6c867a86d8d952e}{dwarf\+\_\+dietype\+\_\+offset()}, which on success returns the offset of the target of the DW\+\_\+\+AT\+\_\+type attribute (if such exists in the \doxylink{group__allstructs_ga3a3759c3047d78dba9f590d5e5893be5}{Dwarf\+\_\+\+Die}). Added a pointer argument so the function can (when appropriate) return a FALSE argument indicating the offset refers to DWARF4 .debug\+\_\+types section, rather than TRUE value when .debug\+\_\+info is the section the offset refers to. If anyone was using this function it would fail badly (while pretending success) with a DWARF4 DW\+\_\+\+FORM\+\_\+ref\+\_\+sig8 on a DW\+\_\+\+AT\+\_\+type attribute from the \doxylink{group__allstructs_ga3a3759c3047d78dba9f590d5e5893be5}{Dwarf\+\_\+\+Die} argument. One will likely encounter DWARF4 content so a single correct function seemed necessary. New regression tests will ensure this will continue to work.

A {\bfseries{compatibility}} change affects callers of \doxylink{group__pubnames_ga10ffe6065920a9dca3f4e29deedce14b}{dwarf\+\_\+get\+\_\+pubtypes()}. If an application reads .debug\+\_\+pubtypes there is a {\bfseries{compatibility break}}. Such applications must be recompiled with latest {\itshape libdwarf}, change \doxylink{group__allstructs_gafa6fe3e82d346650c51a8da418ca431d}{Dwarf\+\_\+\+Type} declarations to use \doxylink{group__allstructs_ga59a6e779b3b390cf4f234c9edee87008}{Dwarf\+\_\+\+Global}, and can only use the latest {\itshape libdwarf}. We are correcting a 1993 library design mistake that created extra work and documentation for library users and inflated the {\itshape libdwarf} API and documentation for no good reason.

The changes are:\+ the data type \doxylink{group__allstructs_gafa6fe3e82d346650c51a8da418ca431d}{Dwarf\+\_\+\+Type} disappears as do dwarf\+\_\+pubtypename() dwarf\+\_\+pubtype\+\_\+die\+\_\+offset(), dwarf\+\_\+pubtype\+\_\+cu\+\_\+offset(), dwarf\+\_\+pubtype\+\_\+name\+\_\+offsets() and dwarf\+\_\+pubtypes\+\_\+dealloc(). Instead the type is \doxylink{group__allstructs_ga59a6e779b3b390cf4f234c9edee87008}{Dwarf\+\_\+\+Global}, the type and functions used for \doxylink{group__pubnames_ga9143be4ff0556383af3a5e4c2de87fff}{dwarf\+\_\+get\+\_\+globals()}. The existing read/\+dealloc functions for \doxylink{group__allstructs_ga59a6e779b3b390cf4f234c9edee87008}{Dwarf\+\_\+\+Global} apply to pubtypes data too.

No one should be referring to the 1990s SGI/\+\+IRIX sections .debug\+\_\+weaknames, .debug\+\_\+funcnames, .debug\+\_\+varnames, or .debug\+\_\+typenames as they are not emitted by any compiler except from SGI/\+\+IRIX/\+\+MIPS in that period. There is (revised) support in {\itshape libdwarf} to read these sections, but we will not mention details here.

Any use of DW\+\_\+\+FORM\+\_\+strx3 or DW\+\_\+\+FORM\+\_\+addrx3 in DWARF would, in 0.\+5.\+0 and earlier, result in {\itshape libdwarf} reporting erroneous data. A copy-\/paste error in libdwarf/\+dwarf\+\_\+util.\+c was noticed and fixed 24 January 2023 for 0.\+6.\+0. Bug {\bfseries{DW202301-\/001}}.

{\bfseries{Changes 0.\+4.\+2 to 0.\+5.\+0}}

v0.\+5.\+0 released 2022-\/11-\/22 The handling of the .debug\+\_\+abbrev data in {\itshape libdwarf} is now more cpu-\/efficient (measurably faster) so access to DIEs and attribute lists is faster. The changes are library-\/internal so are not visible in the API.

Corrects CU and TU indexes in the .debug\+\_\+names (fast access) section to be zero-\/based. The code for that section was previously unusable as it did not follow the DWARF5 documentation.

\doxylink{group__pubnames_ga9143be4ff0556383af3a5e4c2de87fff}{dwarf\+\_\+get\+\_\+globals()} now returns a list of \doxylink{group__allstructs_ga59a6e779b3b390cf4f234c9edee87008}{Dwarf\+\_\+\+Global} names and DIE offsets whether such are defined in the .debug\+\_\+names or .debug\+\_\+pubnames section or both. Previously it only read .debug\+\_\+pubnames.

A new function, \doxylink{group__pubnames_ga98ac98c5bcb56f804a4bdf176b51ea5e}{dwarf\+\_\+global\+\_\+tag\+\_\+number()}, returns the DW\+\_\+\+TAG of any \doxylink{group__allstructs_ga59a6e779b3b390cf4f234c9edee87008}{Dwarf\+\_\+\+Global} that was derived from the .debug\+\_\+names section.

Three new functions enable printing of the .debug\+\_\+addr table. \doxylink{group__debugaddr_gae91d85a860a4dd8e25ab2e9d90810ee0}{dwarf\+\_\+debug\+\_\+addr\+\_\+table()}, \doxylink{group__debugaddr_ga8f0750e184cf03cf7df79a7bcd47b148}{dwarf\+\_\+debug\+\_\+addr\+\_\+by\+\_\+index()}, and \doxylink{group__debugaddr_ga12f5ddb76f71dd3d8583118ef5c0f419}{dwarf\+\_\+dealloc\+\_\+debug\+\_\+addr\+\_\+table()}. Actual use of the table(s) in .debug\+\_\+addr is handled for you when an attribute invoking such is encountered (see DW\+\_\+\+FORM\+\_\+addrx, DW\+\_\+\+FORM\+\_\+addrx1 etc).

Added doc/\+libdwarf.\+dox to the distribution (left out by accident earlier).

{\bfseries{Changes 0.\+4.\+1 to 0.\+4.\+2}}

0.\+4.\+2 released 2022-\/09-\/13. No API changes. No API additions. Corrected a bug in dwarf\+\_\+tsearchhash.\+c where a delete request was accidentally assumed in all hash tree searches. It was invisible to {\itshape libdwarf} uses. Vulnerabilities DW202207-\/001 and DW202208-\/001 were fixed so error conditions when reading fuzzed object files can no longer crash {\itshape libdwarf} (the crash was possible but not certain before the fixes). In this release we believe neither {\itshape libdwarf} nor dwarfdump leak memory even when there are malloc failures. Any GNU debuglink or build-\/id section contents were not being properly freed (if malloced, meaning a compressed section) until 9 September 2022.

It is now possible to run the build sanity tests in all three build mechanisms (configure,cmake,meson) on linux, Macos, Free\+BSD, and Mingw msys2 (windows). {\itshape libdwarf} README.\+md (or README) and README.\+cmake document how to do builds for each supported platform and build mechanism.

{\bfseries{Changes 0.\+4.\+0 to 0.\+4.\+1}}

Reading a carefully corrupted DIE with form DW\+\_\+\+FORM\+\_\+ref\+\_\+sig8 could result in reading memory outside any section, possibly leading to a segmentation violation or other crash. Fixed. \begin{DoxySeeAlso}{See also}
\href{https://www.prevanders.net/dwarfbug.xml}{\texttt{https:\+/\+/\+www.\+prevanders.\+net/\+dwarfbug.\+xml}} DW202206-\/001
\end{DoxySeeAlso}
Reading a carefully corrupted .debug\+\_\+pubnames/\+.debug\+\_\+pubtypes could lead to reading memory outside the section being read, possibly leading to a segmentation violation or other crash. Fixed. \begin{DoxySeeAlso}{See also}
\href{https://www.prevanders.net/dwarfbug.xml}{\texttt{https:\+/\+/\+www.\+prevanders.\+net/\+dwarfbug.\+xml}} DW202205-\/001
\end{DoxySeeAlso}
{\itshape libdwarf} accepts DW\+\_\+\+AT\+\_\+entry\+\_\+pc in a compilation unit DIE as a base address for location lists (though it will prefer DW\+\_\+\+AT\+\_\+low\+\_\+pc if present, per DWARF3). A particular compiler emits DW\+\_\+\+AT\+\_\+entry\+\_\+pc in a DWARF2 object, requiring this change.

{\itshape libdwarf} adds \doxylink{group__gnudebuglink_gae02f80e472417deef078a26c2cafe903}{dwarf\+\_\+suppress\+\_\+debuglink\+\_\+crc()} so that library callers can suppress crc calculations. (useful to save the time of crc when building and testing the same thing(s) over and over; it just loses a little checking.) Additionally, {\itshape libdwarf} now properly handles objects with only GNU debug-\/id or only GNU debuglink.

dwarfdump adds -\/-\/show-\/args, an option to print its arguments and version. Without that new option the version and arguments are not shown. The output of -\/v (-\/-\/version) is a little more complete.

dwarfdump adds -\/-\/suppress-\/debuglink-\/crc, an option to avoid crc calculations when rebuilding and rerunning tests depending on GNU .note.\+gnu.\+buildid or .gnu\+\_\+debuglink sections. The help text and the dwarfdump.\+1 man page are more specific documenting -\/-\/suppress-\/debuglink-\/crc and -\/-\/no-\/follow-\/debuglink

{\bfseries{Changes 0.\+3.\+4 to 0.\+4.\+0}}

Removed the unused \doxylink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error} argument from \doxylink{group__pubnames_ga389e6eed3ca3b715c63d8e64f3a78657}{dwarf\+\_\+return\+\_\+empty\+\_\+pubnames()} as the function can only return DW\+\_\+\+DLV\+\_\+\+OK. dwarf\+\_\+xu\+\_\+header\+\_\+free() renamed to \doxylink{group__splitdwarf_gae7c02412cbb8641585a56102a6e6b36a}{dwarf\+\_\+dealloc\+\_\+xu\+\_\+header()}. dwarf\+\_\+gdbindex\+\_\+free() renamed to \doxylink{group__gdbindex_ga03e8771a5117b782a168d4d1922fe503}{dwarf\+\_\+dealloc\+\_\+gdbindex()}. dwarf\+\_\+loc\+\_\+head\+\_\+c\+\_\+dealloc renamed to \doxylink{group__locations_ga15258867c631414fb4ed048249374e05}{dwarf\+\_\+dealloc\+\_\+loc\+\_\+head\+\_\+c()}.

dwarf\+\_\+get\+\_\+location\+\_\+op\+\_\+value\+\_\+d() renamed to \doxylink{group__locations_ga736d9d65b47aa08977785f3c0629b064}{dwarf\+\_\+get\+\_\+location\+\_\+op\+\_\+value\+\_\+c()}, and 3 pointless arguments removed. The dwarf\+\_\+get\+\_\+location\+\_\+op\+\_\+value\+\_\+d version and the three arguments were added for DWARF5 in libdwarf-\/20210528 but the change was a mistake. Now reverted to the previous version.

The .debug\+\_\+names section interfaces have changed. Added \doxylink{group__debugnames_gae7fca1ebe98511bc1eaaea01b55b208b}{dwarf\+\_\+dnames\+\_\+offsets()} to provide details of facts useful in problems reading the section. \doxylink{group__debugnames_gadfb161993f617a4a233583ec5745de6a}{dwarf\+\_\+dnames\+\_\+name()} now does work and the interface was changed to make it easier to use.

{\bfseries{Changes 0.\+3.\+3 to 0.\+3.\+4}}

Replaced the groff -\/mm based libdwarf.\+pdf with a libdwarf.\+pdf generated by doxygen and latex.

Added support for the meson build system.

Updated an include in libdwarfp source files. Improved doxygen documentation of {\itshape libdwarf}. Now \textquotesingle{}make check -\/j8\textquotesingle{} and the like works correctly. Fixed a bug where reading a PE (Windows) object could fail for certain section virtual size values. Added initializers to two uninitialized local variables in dwarfdump source so a compiler warning cannot not kill a --enable-\/wall build.

Added \doxylink{showsectiongroups_8c}{src/\+bin/\+dwarfexample/\+showsectiongroups.\+c} so it is easy to see what groups are present in an object without all the other dwarfdump output.

{\bfseries{Changes 20210528 to 0.\+3.\+3 (28 January 2022) }}

There were major revisions in going from date versioning to Semantic Versioning. Many functions were deleted and various functions changed their list of arguments. Many many filenames changed. Include lists were simplified. Far too much changed to list here. 