1.\" $NetBSD: dwarf_transform_to_disk_form.3,v 1.2 2014/03/09 16:58:04 christos Exp $ 2.\" 3.\" Copyright (c) 2011 Kai Wang 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" Id: dwarf_transform_to_disk_form.3 2075 2011-10-27 03:47:28Z jkoshy 28.\" 29.Dd August 25, 2011 30.Os 31.Dt DWARF_TRANSFORM_TO_DISK_FORM 3 32.Sh NAME 33.Nm dwarf_transform_to_disk_form 34.Nd transform DWARF information into byte streams 35.Sh LIBRARY 36.Lb libdwarf 37.Sh SYNOPSIS 38.In libdwarf.h 39.Ft Dwarf_Signed 40.Fo dwarf_transform_to_disk_form 41.Fa "Dwarf_P_Debug dbg" 42.Fa "Dwarf_Error *err" 43.Fc 44.Sh DESCRIPTION 45Function 46.Fn dwarf_transform_to_disk_form 47transforms the DWARF information gathered by the producer into 48byte streams for the application to write out as ELF sections. 49If the flag 50.Dv DW_DLC_SYMBOLIC_RELOCATIONS 51is set on the producer, the function will also generate the associated 52relocation arrays. 53.Pp 54Argument 55.Ar dbg 56should reference a DWARF producer instance allocated using 57.Xr dwarf_producer_init 3 58or 59.Xr dwarf_producer_init_b 3 . 60.Pp 61If argument 62.Ar err 63is not NULL, it will be used to store error information in case 64of an error. 65.Pp 66After a call to this function, the application can call the function 67.Xr dwarf_get_section_bytes 3 68to retrieve the byte streams for each ELF section. 69If the flag 70.Dv DW_DLC_SYMBOLIC_RELOCATIONS 71was set on the descriptor, the application can also call the function 72.Xr dwarf_get_relocation_info 3 73to retrieve the generated relocation arrays. 74.Sh RETURN VALUES 75On success, function 76.Fn dwarf_transform_to_disk_form 77returns the total number of ELF sections generated. 78In case of an error, function 79.Fn dwarf_transform_to_disk_form 80returns 81.Dv DW_DLV_NOCOUNT 82and sets the argument 83.Ar err . 84.Sh ERRORS 85Function 86.Fn dwarf_transform_to_disk_form 87can fail with: 88.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 89.It Bq Er DW_DLE_ARGUMENT 90Argument 91.Ar dbg 92was NULL. 93.It Bq Er DW_DLE_MEMORY 94An out of memory condition was encountered during execution. 95.El 96.Sh SEE ALSO 97.Xr dwarf 3 , 98.Xr dwarf_get_relocation_info 3 , 99.Xr dwarf_get_section_bytes 3 , 100.Xr dwarf_producer_init 3 , 101.Xr dwarf_producer_init_b 3 102