\doxysection{Access GNU .gnu\+\_\+debuglink, build-\/id. }
\hypertarget{group__gnudebuglink}{}\label{group__gnudebuglink}\index{Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}}
\doxysubsubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
DW\+\_\+\+API int \doxymbox{\hyperlink{group__gnudebuglink_ga02541e74c5da6d90fd8c2140bb6d652f}{dwarf\+\_\+gnu\+\_\+debuglink}} (\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug}} dw\+\_\+dbg, char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}dw\+\_\+debuglink\+\_\+path\+\_\+returned, unsigned char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}dw\+\_\+crc\+\_\+returned, char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}dw\+\_\+debuglink\+\_\+fullpath\+\_\+returned, unsigned int \texorpdfstring{$\ast$}{*}dw\+\_\+debuglink\+\_\+path\+\_\+length\+\_\+returned, unsigned int \texorpdfstring{$\ast$}{*}dw\+\_\+buildid\+\_\+type\+\_\+returned, char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}dw\+\_\+buildid\+\_\+owner\+\_\+name\+\_\+returned, unsigned char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}dw\+\_\+buildid\+\_\+returned, unsigned int \texorpdfstring{$\ast$}{*}dw\+\_\+buildid\+\_\+length\+\_\+returned, char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}dw\+\_\+paths\+\_\+returned, unsigned int \texorpdfstring{$\ast$}{*}dw\+\_\+paths\+\_\+length\+\_\+returned, \doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error}} \texorpdfstring{$\ast$}{*}dw\+\_\+error)
\begin{DoxyCompactList}\small\item\em Find a separated DWARF object file. \end{DoxyCompactList}\item 
DW\+\_\+\+API int \doxymbox{\hyperlink{group__gnudebuglink_gae02f80e472417deef078a26c2cafe903}{dwarf\+\_\+suppress\+\_\+debuglink\+\_\+crc}} (int dw\+\_\+suppress)
\begin{DoxyCompactList}\small\item\em Suppressing crc calculations. \end{DoxyCompactList}\item 
DW\+\_\+\+API int \doxymbox{\hyperlink{group__gnudebuglink_gaf2024c1cacfd82216fedb1c54e4f8561}{dwarf\+\_\+add\+\_\+debuglink\+\_\+global\+\_\+path}} (\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug}} dw\+\_\+dbg, const char \texorpdfstring{$\ast$}{*}dw\+\_\+pathname, \doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error}} \texorpdfstring{$\ast$}{*}dw\+\_\+error)
\begin{DoxyCompactList}\small\item\em Adding debuglink global paths. \end{DoxyCompactList}\item 
DW\+\_\+\+API int \doxymbox{\hyperlink{group__gnudebuglink_gaeeadbc3db3ece37f4b302bf1d5da12ea}{dwarf\+\_\+crc32}} (\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug}} dw\+\_\+dbg, unsigned char \texorpdfstring{$\ast$}{*}dw\+\_\+crcbuf, \doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error}} \texorpdfstring{$\ast$}{*}dw\+\_\+error)
\begin{DoxyCompactList}\small\item\em Crc32 used for debuglink crc calculation. \end{DoxyCompactList}\item 
DW\+\_\+\+API unsigned int \doxymbox{\hyperlink{group__gnudebuglink_ga4d2853b552c5a4b353bf6acd64972080}{dwarf\+\_\+basic\+\_\+crc32}} (const unsigned char \texorpdfstring{$\ast$}{*}dw\+\_\+buf, unsigned long dw\+\_\+len, unsigned int dw\+\_\+init)
\begin{DoxyCompactList}\small\item\em Public interface to the real crc calculation. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
When DWARF sections are in a different object than the executable or a normal shared object. The special GNU section provides a way to name the object file with DWARF.

libdwarf will attempt to use this data to find the object file with DWARF.

Has nothing to do with split-\/dwarf/\+debug-\/fission. 

\label{doc-func-members}
\Hypertarget{group__gnudebuglink_doc-func-members}
\doxysubsection{Function Documentation}
\Hypertarget{group__gnudebuglink_gaf2024c1cacfd82216fedb1c54e4f8561}\index{Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}!dwarf\_add\_debuglink\_global\_path@{dwarf\_add\_debuglink\_global\_path}}
\index{dwarf\_add\_debuglink\_global\_path@{dwarf\_add\_debuglink\_global\_path}!Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}}
\doxysubsubsection{\texorpdfstring{dwarf\_add\_debuglink\_global\_path()}{dwarf\_add\_debuglink\_global\_path()}}
{\footnotesize\ttfamily \label{group__gnudebuglink_gaf2024c1cacfd82216fedb1c54e4f8561} 
DW\+\_\+\+API int dwarf\+\_\+add\+\_\+debuglink\+\_\+global\+\_\+path (\begin{DoxyParamCaption}\item[{\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug}}}]{dw\+\_\+dbg}{, }\item[{const char \texorpdfstring{$\ast$}{*}}]{dw\+\_\+pathname}{, }\item[{\doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error}} \texorpdfstring{$\ast$}{*}}]{dw\+\_\+error}{}\end{DoxyParamCaption})}



Adding debuglink global paths. 

Used inside src/\+bin/\+dwarfexample/\+dwdebuglink.\+c so we can show all that is going on. The following has the explanation for how debuglink and global paths interact:\+ \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}

\begin{DoxyParams}{Parameters}
{\em dw\+\_\+dbg} & Pass in the \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} of interest. \\
\hline
{\em dw\+\_\+pathname} & Pass in a pathname to add to the list of global paths used by debuglink. \\
\hline
{\em dw\+\_\+error} & The usual pointer to return error details. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Returns DW\+\_\+\+DLV\+\_\+\+OK etc. 
\end{DoxyReturn}
\Hypertarget{group__gnudebuglink_ga4d2853b552c5a4b353bf6acd64972080}\index{Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}!dwarf\_basic\_crc32@{dwarf\_basic\_crc32}}
\index{dwarf\_basic\_crc32@{dwarf\_basic\_crc32}!Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}}
\doxysubsubsection{\texorpdfstring{dwarf\_basic\_crc32()}{dwarf\_basic\_crc32()}}
{\footnotesize\ttfamily \label{group__gnudebuglink_ga4d2853b552c5a4b353bf6acd64972080} 
DW\+\_\+\+API unsigned int dwarf\+\_\+basic\+\_\+crc32 (\begin{DoxyParamCaption}\item[{const unsigned char \texorpdfstring{$\ast$}{*}}]{dw\+\_\+buf}{, }\item[{unsigned long}]{dw\+\_\+len}{, }\item[{unsigned int}]{dw\+\_\+init}{}\end{DoxyParamCaption})}



Public interface to the real crc calculation. 

It is unlikely this is useful. The calculation will not produce a return matching that of Linux/\+\+Macos if the compiler implements unsigned int or signed int as 16 bits long.

The caller must guarantee that dw\+\_\+buf is non-\/null and pointing to dw\+\_\+len bytes of readable memory. If dw\+\_\+buf is NULL then 0 is immediately returned and there is no indication of error.


\begin{DoxyParams}{Parameters}
{\em dw\+\_\+buf} & Pass in a pointer to some bytes on which the crc calculation as done in debuglink is to be done. \\
\hline
{\em dw\+\_\+len} & Pass in the length in bytes of dw\+\_\+buf. \\
\hline
{\em dw\+\_\+init} & Pass in the initial 32 bit value, zero is the right choice. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Returns an int (assumed 32 bits int!) with the calculated crc. 
\end{DoxyReturn}
\Hypertarget{group__gnudebuglink_gaeeadbc3db3ece37f4b302bf1d5da12ea}\index{Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}!dwarf\_crc32@{dwarf\_crc32}}
\index{dwarf\_crc32@{dwarf\_crc32}!Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}}
\doxysubsubsection{\texorpdfstring{dwarf\_crc32()}{dwarf\_crc32()}}
{\footnotesize\ttfamily \label{group__gnudebuglink_gaeeadbc3db3ece37f4b302bf1d5da12ea} 
DW\+\_\+\+API int dwarf\+\_\+crc32 (\begin{DoxyParamCaption}\item[{\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug}}}]{dw\+\_\+dbg}{, }\item[{unsigned char \texorpdfstring{$\ast$}{*}}]{dw\+\_\+crcbuf}{, }\item[{\doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error}} \texorpdfstring{$\ast$}{*}}]{dw\+\_\+error}{}\end{DoxyParamCaption})}



Crc32 used for debuglink crc calculation. 

Caller passes pointer to array of 4 unsigned char provided by the caller and if this returns DW\+\_\+\+DLV\+\_\+\+OK that array is filled in.

Callers must guarantee dw\+\_\+crcbuf points to at least 4 bytes of writable memory. Passing in a null dw\+\_\+crcbug results in an immediate return of DW\+\_\+\+DLV\+\_\+\+NO\+\_\+\+ENTRY and the pointer is not used.


\begin{DoxyParams}{Parameters}
{\em dw\+\_\+dbg} & Pass in an open dw\+\_\+dbg. When you attempted to open it, and it succeeded then pass the it via the \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} The function reads the file into memory and performs a crc calculation. \\
\hline
{\em dw\+\_\+crcbuf} & Pass in a pointer to a 4 byte area to hold the returned crc, on success the function puts the 4 bytes there. \\
\hline
{\em dw\+\_\+error} & The usual pointer to return error details. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Returns DW\+\_\+\+DLV\+\_\+\+OK etc. 
\end{DoxyReturn}
\Hypertarget{group__gnudebuglink_ga02541e74c5da6d90fd8c2140bb6d652f}\index{Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}!dwarf\_gnu\_debuglink@{dwarf\_gnu\_debuglink}}
\index{dwarf\_gnu\_debuglink@{dwarf\_gnu\_debuglink}!Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}}
\doxysubsubsection{\texorpdfstring{dwarf\_gnu\_debuglink()}{dwarf\_gnu\_debuglink()}}
{\footnotesize\ttfamily \label{group__gnudebuglink_ga02541e74c5da6d90fd8c2140bb6d652f} 
DW\+\_\+\+API int dwarf\+\_\+gnu\+\_\+debuglink (\begin{DoxyParamCaption}\item[{\doxymbox{\hyperlink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug}}}]{dw\+\_\+dbg}{, }\item[{char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}}]{dw\+\_\+debuglink\+\_\+path\+\_\+returned}{, }\item[{unsigned char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}}]{dw\+\_\+crc\+\_\+returned}{, }\item[{char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}}]{dw\+\_\+debuglink\+\_\+fullpath\+\_\+returned}{, }\item[{unsigned int \texorpdfstring{$\ast$}{*}}]{dw\+\_\+debuglink\+\_\+path\+\_\+length\+\_\+returned}{, }\item[{unsigned int \texorpdfstring{$\ast$}{*}}]{dw\+\_\+buildid\+\_\+type\+\_\+returned}{, }\item[{char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}}]{dw\+\_\+buildid\+\_\+owner\+\_\+name\+\_\+returned}{, }\item[{unsigned char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}}]{dw\+\_\+buildid\+\_\+returned}{, }\item[{unsigned int \texorpdfstring{$\ast$}{*}}]{dw\+\_\+buildid\+\_\+length\+\_\+returned}{, }\item[{char \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}}]{dw\+\_\+paths\+\_\+returned}{, }\item[{unsigned int \texorpdfstring{$\ast$}{*}}]{dw\+\_\+paths\+\_\+length\+\_\+returned}{, }\item[{\doxymbox{\hyperlink{group__allstructs_ga8d4fac0e48040b6ca91e06ffda09766a}{Dwarf\+\_\+\+Error}} \texorpdfstring{$\ast$}{*}}]{dw\+\_\+error}{}\end{DoxyParamCaption})}



Find a separated DWARF object file. 

.gnu\+\_\+debuglink and/\+or the section .note.\+gnu.\+build-\/id.

Unless something is odd and you want to know details of the two sections you will not need this function.

\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}}

\doxylink{group__exampledebuglink}{Using GNU debuglink data}
\end{DoxySeeAlso}
If no debuglink then name\+\_\+returned,crc\+\_\+returned and debuglink\+\_\+path\+\_\+returned will get set 0 through the pointers.

If no .note.\+gnu.\+build-\/id then buildid\+\_\+length\+\_\+returned, and buildid\+\_\+returned will be set 0 through the pointers.

In most cases output arguments can be passed as zero and the function will simply not return data through such arguments. Useful if you only care about some of the data potentially returned.

If dw\+\_\+debuglink\+\_\+fullpath returned is set by the call the space allocated must be freed by the caller with free(dw\+\_\+debuglink\+\_\+fullpath\+\_\+returned).

if dw\+\_\+debuglink\+\_\+paths\+\_\+returned is set by the call the space allocated must be free by the caller with free(dw\+\_\+debuglink\+\_\+paths\+\_\+returned).

\doxylink{group__initfunctions_ga14a505c07ee5481401735f280f719454}{dwarf\+\_\+finish()} will not free strings dw\+\_\+debuglink\+\_\+fullpath\+\_\+returned or dw\+\_\+debuglink\+\_\+paths\+\_\+returned.


\begin{DoxyParams}{Parameters}
{\em dw\+\_\+dbg} & The \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} of interest. \\
\hline
{\em dw\+\_\+debuglink\+\_\+path\+\_\+returned} & On success returns a pointer to a path in the debuglink section. Do not free! \\
\hline
{\em dw\+\_\+crc\+\_\+returned} & On success returns a pointer to a 4 byte area through the pointer. \\
\hline
{\em dw\+\_\+debuglink\+\_\+fullpath\+\_\+returned} & On success returns a pointer to a full path computed from debuglink data of a correct path to a file with DWARF sections. Free this string when no longer of interest. \\
\hline
{\em dw\+\_\+debuglink\+\_\+path\+\_\+length\+\_\+returned} & On success returns the strlen() of dw\+\_\+debuglink\+\_\+fullpath\+\_\+returned . \\
\hline
{\em dw\+\_\+buildid\+\_\+type\+\_\+returned} & On success returns a pointer to integer with a type code. See the buildid definition. \\
\hline
{\em dw\+\_\+buildid\+\_\+owner\+\_\+name\+\_\+returned} & On success returns a pointer to the owner name from the buildid section. Do not free this. \\
\hline
{\em dw\+\_\+buildid\+\_\+returned} & On success returns a pointer to a sequence of bytes containing the buildid. \\
\hline
{\em dw\+\_\+buildid\+\_\+length\+\_\+returned} & On success this is set to the length of the set of bytes pointed to by dw\+\_\+buildid\+\_\+returned . \\
\hline
{\em dw\+\_\+paths\+\_\+returned} & On success sets a pointer to an array of pointers to strings, each with a global path. These strings must be freed by the caller, \doxylink{group__initfunctions_ga14a505c07ee5481401735f280f719454}{dwarf\+\_\+finish()} will not free these strings. Call free(dw\+\_\+paths\+\_\+returned).\\
\hline
{\em dw\+\_\+paths\+\_\+length\+\_\+returned} & On success returns the length of the array of string pointers dw\+\_\+paths\+\_\+returned points at. \\
\hline
{\em dw\+\_\+error} & The usual pointer to return error details. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Returns DW\+\_\+\+DLV\+\_\+\+OK etc. 
\end{DoxyReturn}
\Hypertarget{group__gnudebuglink_gae02f80e472417deef078a26c2cafe903}\index{Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}!dwarf\_suppress\_debuglink\_crc@{dwarf\_suppress\_debuglink\_crc}}
\index{dwarf\_suppress\_debuglink\_crc@{dwarf\_suppress\_debuglink\_crc}!Access GNU .gnu\_debuglink, build-\/id.@{Access GNU .gnu\_debuglink, build-\/id.}}
\doxysubsubsection{\texorpdfstring{dwarf\_suppress\_debuglink\_crc()}{dwarf\_suppress\_debuglink\_crc()}}
{\footnotesize\ttfamily \label{group__gnudebuglink_gae02f80e472417deef078a26c2cafe903} 
DW\+\_\+\+API int dwarf\+\_\+suppress\+\_\+debuglink\+\_\+crc (\begin{DoxyParamCaption}\item[{int}]{dw\+\_\+suppress}{}\end{DoxyParamCaption})}



Suppressing crc calculations. 

The .gnu\+\_\+debuglink section contains a compilation-\/system created crc (4 byte) value. If dwarf\+\_\+init\+\_\+path\+[\+\_\+dl]\+() is called such a section can result in the reader/\+consumer calculating the crc value of a different object file. Which on a large object file could seem slow. See \href{https://en.wikipedia.org/wiki/Cyclic_redundancy_check}{\texttt{https:\+/\+/\+en.\+wikipedia.\+org/\+wiki/\+\+Cyclic\+\_\+redundancy\+\_\+check}}

When one is confident that any debug\+\_\+link file found is the appropriate one one can call dwarf\+\_\+suppress\+\_\+debuglink\+\_\+crc with a non-\/zero argument and any dwarf\+\_\+init\+\_\+path\+[\+\_\+dl]\+ call will skip debuglink crc calculations and just assume the crc would match whenever it applies. This is a global flag, applies to all \doxylink{group__allstructs_gac2ba1e1c1b70a3191506b414195ca807}{Dwarf\+\_\+\+Debug} opened after the call in the program execution.

Does not apply to the .note.\+gnu.\+buildid section as that section never implies the reader/\+consumer needs to do a crc calculation.


\begin{DoxyParams}{Parameters}
{\em dw\+\_\+suppress} & Pass in 1 to suppress future calculation of crc values to verify a debuglink target is correct. So use only when you know this is safe. Pass in 0 to ensure future dwarf\+\_\+init\+\_\+path\+\_\+dl calls compute debuglink CRC values as required. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Returns the previous value of the global flag.
\end{DoxyReturn}
\doxylink{index_dwsec_separatedebug}{Details on separate DWARF object access } 