1.\" $NetBSD: dwarf_transform_to_disk_form.3,v 1.6 2024/03/03 17:37:32 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 3963 2022-03-12 16:07:32Z jkoshy 28.\" 29.Dd August 25, 2011 30.Dt DWARF_TRANSFORM_TO_DISK_FORM 3 31.Os 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.Fa 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.Fa err 63is not 64.Dv NULL , 65it will be used to store error information in case of an error. 66.Pp 67After a call to this function, the application can call the function 68.Xr dwarf_get_section_bytes 3 69to retrieve the byte streams for each ELF section. 70If the flag 71.Dv DW_DLC_SYMBOLIC_RELOCATIONS 72was set on the descriptor, the application can also call the function 73.Xr dwarf_get_relocation_info 3 74to retrieve the generated relocation arrays. 75.Sh RETURN VALUES 76On success, function 77.Fn dwarf_transform_to_disk_form 78returns the total number of ELF sections generated. 79In case of an error, function 80.Fn dwarf_transform_to_disk_form 81returns 82.Dv DW_DLV_NOCOUNT 83and sets the argument 84.Fa err . 85.Sh ERRORS 86Function 87.Fn dwarf_transform_to_disk_form 88can fail with: 89.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 90.It Bq Er DW_DLE_ARGUMENT 91Argument 92.Fa dbg 93was 94.Dv NULL . 95.It Bq Er DW_DLE_MEMORY 96An out of memory condition was encountered during execution. 97.El 98.Sh SEE ALSO 99.Xr dwarf 3 , 100.Xr dwarf_get_relocation_info 3 , 101.Xr dwarf_get_section_bytes 3 , 102.Xr dwarf_producer_init 3 , 103.Xr dwarf_producer_init_b 3 104