1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association. 12.\" 13.Dd December 07, 2020 14.Dt ctfconvert 1ONBLD 15.Os 16.Sh NAME 17.Nm ctfconvert 18.Nd Convert ELF object debug data to CTF container 19.Sh SYNOPSIS 20.Nm 21.Op Fl fikms 22.Op Fl b Ar batchsize 23.Op Fl j Ar threads 24.Op Fl l Ar label | Fl L Ar labelenv 25.Op Fl M Ar ignorefile 26.Op Fl o Ar outfile 27.Ar ELF_object 28.Sh DESCRIPTION 29The 30.Nm 31utility converts debug information found within 32.Ar ELF_object 33to CTF data and adds this to a CTF container. 34.Ar ELF_object 35can be a single object file or a fully linked object such as a shared library 36or binary. 37.Nm 38currently supports input debug data in DWARFv2 or DWARFv4 format. 39Unless the 40.Fl o 41option is present, this is done in-place; the original file being modified 42with a new CTF container being added. 43For in-place processing, unless the 44.Fl k 45option is present, the source file will be removed if an error occurs. 46.Sh OPTIONS 47The following options are supported: 48.Bl -tag -width Ar 49.It Fl f 50Always attempt conversion. 51This option causes 52.Nm 53to attempt conversion even for files where it does not seem appropriate. 54This is occasionally necessary to convert objects which have had some 55local symbols removed from the symbol table. 56.It Fl i 57Ignore files not built partially from C sources. 58.Nm 59will usually check 60.Ar ELF_object 61to see if at least one of the input files was a 62.Sq .c 63file, and exit with an error if not. 64With the 65.Fl i 66option, the check is still done but 67.Nm 68will exit with a success status instead of an error. 69In either case, conversion is not attempted. 70To attempt conversion even when the object does not appear to have been built 71from C sources, use the 72.Fl f 73option. 74.It Fl k 75When processing a file in-place and an error occurs, keep the input file 76rather than deleting it. 77.It Fl m 78Allow 79.Ar ELF_object 80to have missing debug data. 81By default, 82.Nm 83requires that each C source compilation unit in 84.Ar ELF_object 85contains debug data, and will exit with an error if this is not the case. 86The 87.Fl m 88option relaxes this restriction allowing processing of such files. 89Note that if the file contains no debug data in any of the compilation units 90then this flag will cause 91.Nm 92to exit successfully without taking any action, and can mask missing debug data. 93.It Fl M Ar ignorefile 94Allow 95.Ar ELF_object 96to have missing debug data in selected source files. 97The source files to ignore are specified as a list of file basenames (without 98any directory component) in 99.Ar ignorefile . 100Each file should be listed on its own line, separated by a newline. 101It is not possible to encode a file name that contains a newline and any other 102white-space within the line is considered to be part of the file name being 103specified. 104The 105.Sq / 106character may not appear in the file name. 107Empty lines and any line which has a 108.Sq # 109character in the first column are ignored. 110.It Fl b Ar batchsize 111Batch-process this many compilation units from the source file at once (default 112256). This helps to reduce memory usage when processing large objects which 113were built from many source files. 114.It Fl j Ar threads 115Use this many threads to perform the merge (default 4). 116.It Fl l Ar label 117Set the output container's label to the specified value. 118.It Fl L Ar labelenv 119Set the output container's label to the value of the specified environment 120variable. 121.It Fl o Ar outfile 122Write the new object with added CTF ta to the specified output file, rather 123than updating the input in-place. 124.It Fl s 125This option allows truncation of data that cannot be converted to CTF format 126because it exceeds the allowed size. 127Without this option being provided, conversion of such data would produce a 128fatal error. 129The current implementation allows truncation of 130.Vt enum 131definitions. 132When this occurs the resulting CTF data does not contain all possible 133.Vt enum 134values and a warning will be produced for each truncation. 135.El 136.Sh OPERANDS 137The following operands are supported: 138.Bl -tag -width Ar 139.It Ar object_file 140The source object file to process. 141.El 142.Sh EXIT STATUS 143.Bl -inset 144.It Sy 0 145.Dl Execution completed successfully. 146.It Sy 1 147.Dl A fatal error occurred. 148.It Sy 2 149.Dl Invalid command line options were specified. 150.El 151.Sh INTERFACE STABILITY 152The command line interface of 153.Nm 154is 155.Sy Uncommitted . 156The output of 157.Nm 158is 159.Sy Not-An-Interface 160and may change at any time. 161.Sh SEE ALSO 162.Xr ctfdiff 1 , 163.Xr ctfdump 1 , 164.Xr ctf 4 165