1effb27eeSAndy Fiddaman.\"
2effb27eeSAndy Fiddaman.\" This file and its contents are supplied under the terms of the
3effb27eeSAndy Fiddaman.\" Common Development and Distribution License ("CDDL"), version 1.0.
4effb27eeSAndy Fiddaman.\" You may only use this file in accordance with the terms of version
5effb27eeSAndy Fiddaman.\" 1.0 of the CDDL.
6effb27eeSAndy Fiddaman.\"
7effb27eeSAndy Fiddaman.\" A full copy of the text of the CDDL should have accompanied this
8effb27eeSAndy Fiddaman.\" source.  A copy of the CDDL is also available via the Internet at
9effb27eeSAndy Fiddaman.\" http://www.illumos.org/license/CDDL.
10effb27eeSAndy Fiddaman.\"
11effb27eeSAndy Fiddaman.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
12effb27eeSAndy Fiddaman.\"
13*88a08813SAndy Fiddaman.Dd December 07, 2020
14effb27eeSAndy Fiddaman.Dt ctfconvert 1ONBLD
15effb27eeSAndy Fiddaman.Os
16effb27eeSAndy Fiddaman.Sh NAME
17effb27eeSAndy Fiddaman.Nm ctfconvert
18effb27eeSAndy Fiddaman.Nd Convert ELF object debug data to CTF container
19effb27eeSAndy Fiddaman.Sh SYNOPSIS
20effb27eeSAndy Fiddaman.Nm
2173197b54SAndy Fiddaman.Op Fl fikms
22effb27eeSAndy Fiddaman.Op Fl b Ar batchsize
23effb27eeSAndy Fiddaman.Op Fl j Ar threads
24effb27eeSAndy Fiddaman.Op Fl l Ar label | Fl L Ar labelenv
25*88a08813SAndy Fiddaman.Op Fl M Ar ignorefile
26effb27eeSAndy Fiddaman.Op Fl o Ar outfile
27effb27eeSAndy Fiddaman.Ar ELF_object
28effb27eeSAndy Fiddaman.Sh DESCRIPTION
29effb27eeSAndy FiddamanThe
30effb27eeSAndy Fiddaman.Nm
31effb27eeSAndy Fiddamanutility converts debug information found within
32effb27eeSAndy Fiddaman.Ar ELF_object
33effb27eeSAndy Fiddamanto CTF data and adds this to a CTF container.
34effb27eeSAndy Fiddaman.Ar ELF_object
35effb27eeSAndy Fiddamancan be a single object file or a fully linked object such as a shared library
36effb27eeSAndy Fiddamanor binary.
37effb27eeSAndy Fiddaman.Nm
38effb27eeSAndy Fiddamancurrently supports input debug data in DWARFv2 or DWARFv4 format.
39effb27eeSAndy FiddamanUnless the
40effb27eeSAndy Fiddaman.Fl o
41effb27eeSAndy Fiddamanoption is present, this is done in-place; the original file being modified
42effb27eeSAndy Fiddamanwith a new CTF container being added.
43effb27eeSAndy FiddamanFor in-place processing, unless the
44effb27eeSAndy Fiddaman.Fl k
45effb27eeSAndy Fiddamanoption is present, the source file will be removed if an error occurs.
46effb27eeSAndy Fiddaman.Sh OPTIONS
47effb27eeSAndy FiddamanThe following options are supported:
48effb27eeSAndy Fiddaman.Bl -tag -width Ar
4973197b54SAndy Fiddaman.It Fl f
5073197b54SAndy FiddamanAlways attempt conversion.
5173197b54SAndy FiddamanThis option causes
5273197b54SAndy Fiddaman.Nm
5373197b54SAndy Fiddamanto attempt conversion even for files where it does not seem appropriate.
5473197b54SAndy FiddamanThis is occasionally necessary to convert objects which have had some
5573197b54SAndy Fiddamanlocal symbols removed from the symbol table.
56effb27eeSAndy Fiddaman.It Fl i
57effb27eeSAndy FiddamanIgnore files not built partially from C sources.
58effb27eeSAndy Fiddaman.Nm
59effb27eeSAndy Fiddamanwill usually check
60effb27eeSAndy Fiddaman.Ar ELF_object
61effb27eeSAndy Fiddamanto see if at least one of the input files was a
62effb27eeSAndy Fiddaman.Sq .c
63effb27eeSAndy Fiddamanfile, and exit with an error if not.
6473197b54SAndy FiddamanWith the
65effb27eeSAndy Fiddaman.Fl i
6673197b54SAndy Fiddamanoption, the check is still done but
6773197b54SAndy Fiddaman.Nm
6873197b54SAndy Fiddamanwill exit with a success status instead of an error.
6973197b54SAndy FiddamanIn either case, conversion is not attempted.
7073197b54SAndy FiddamanTo attempt conversion even when the object does not appear to have been built
7173197b54SAndy Fiddamanfrom C sources, use the
7273197b54SAndy Fiddaman.Fl f
7373197b54SAndy Fiddamanoption.
74effb27eeSAndy Fiddaman.It Fl k
75effb27eeSAndy FiddamanWhen processing a file in-place and an error occurs, keep the input file
76effb27eeSAndy Fiddamanrather than deleting it.
77effb27eeSAndy Fiddaman.It Fl m
78effb27eeSAndy FiddamanAllow
79effb27eeSAndy Fiddaman.Ar ELF_object
80effb27eeSAndy Fiddamanto have missing debug data.
81effb27eeSAndy FiddamanBy default,
82effb27eeSAndy Fiddaman.Nm
83effb27eeSAndy Fiddamanrequires that each C source compilation unit in
84effb27eeSAndy Fiddaman.Ar ELF_object
85effb27eeSAndy Fiddamancontains debug data, and will exit with an error if this is not the case.
86effb27eeSAndy FiddamanThe
87effb27eeSAndy Fiddaman.Fl m
88effb27eeSAndy Fiddamanoption relaxes this restriction allowing processing of such files.
89effb27eeSAndy FiddamanNote that if the file contains no debug data in any of the compilation units
90effb27eeSAndy Fiddamanthen this flag will cause
91effb27eeSAndy Fiddaman.Nm
92dd442252SAndy Fiddamanto exit successfully without taking any action, and can mask missing debug data.
93*88a08813SAndy Fiddaman.It Fl M Ar ignorefile
94*88a08813SAndy FiddamanAllow
95*88a08813SAndy Fiddaman.Ar ELF_object
96*88a08813SAndy Fiddamanto have missing debug data in selected source files.
97*88a08813SAndy FiddamanThe source files to ignore are specified as a list of file basenames (without
98*88a08813SAndy Fiddamanany directory component) in
99*88a08813SAndy Fiddaman.Ar ignorefile .
100*88a08813SAndy FiddamanEach file should be listed on its own line, separated by a newline.
101*88a08813SAndy FiddamanIt is not possible to encode a file name that contains a newline and any other
102*88a08813SAndy Fiddamanwhite-space within the line is considered to be part of the file name being
103*88a08813SAndy Fiddamanspecified.
104*88a08813SAndy FiddamanThe
105*88a08813SAndy Fiddaman.Sq /
106*88a08813SAndy Fiddamancharacter may not appear in the file name.
107*88a08813SAndy FiddamanEmpty lines and any line which has a
108*88a08813SAndy Fiddaman.Sq #
109*88a08813SAndy Fiddamancharacter in the first column are ignored.
110effb27eeSAndy Fiddaman.It Fl b Ar batchsize
111effb27eeSAndy FiddamanBatch-process this many compilation units from the source file at once (default
112effb27eeSAndy Fiddaman256). This helps to reduce memory usage when processing large objects which
113effb27eeSAndy Fiddamanwere built from many source files.
114effb27eeSAndy Fiddaman.It Fl j Ar threads
115effb27eeSAndy FiddamanUse this many threads to perform the merge (default 4).
116effb27eeSAndy Fiddaman.It Fl l Ar label
117effb27eeSAndy FiddamanSet the output container's label to the specified value.
118effb27eeSAndy Fiddaman.It Fl L Ar labelenv
119effb27eeSAndy FiddamanSet the output container's label to the value of the specified environment
120effb27eeSAndy Fiddamanvariable.
121effb27eeSAndy Fiddaman.It Fl o Ar outfile
122effb27eeSAndy FiddamanWrite the new object with added CTF ta to the specified output file, rather
123effb27eeSAndy Fiddamanthan updating the input in-place.
124dd442252SAndy Fiddaman.It Fl s
125dd442252SAndy FiddamanThis option allows truncation of data that cannot be converted to CTF format
126dd442252SAndy Fiddamanbecause it exceeds the allowed size.
127dd442252SAndy FiddamanWithout this option being provided, conversion of such data would produce a
128dd442252SAndy Fiddamanfatal error.
129dd442252SAndy FiddamanThe current implementation allows truncation of
130dd442252SAndy Fiddaman.Vt enum
131dd442252SAndy Fiddamandefinitions.
132dd442252SAndy FiddamanWhen this occurs the resulting CTF data does not contain all possible
133dd442252SAndy Fiddaman.Vt enum
134dd442252SAndy Fiddamanvalues and a warning will be produced for each truncation.
135effb27eeSAndy Fiddaman.El
136effb27eeSAndy Fiddaman.Sh OPERANDS
137effb27eeSAndy FiddamanThe following operands are supported:
138effb27eeSAndy Fiddaman.Bl -tag -width Ar
139effb27eeSAndy Fiddaman.It Ar object_file
140effb27eeSAndy FiddamanThe source object file to process.
141effb27eeSAndy Fiddaman.El
142effb27eeSAndy Fiddaman.Sh EXIT STATUS
143effb27eeSAndy Fiddaman.Bl -inset
144effb27eeSAndy Fiddaman.It Sy 0
145effb27eeSAndy Fiddaman.Dl Execution completed successfully.
146effb27eeSAndy Fiddaman.It Sy 1
147effb27eeSAndy Fiddaman.Dl A fatal error occurred.
148effb27eeSAndy Fiddaman.It Sy 2
149effb27eeSAndy Fiddaman.Dl Invalid command line options were specified.
150effb27eeSAndy Fiddaman.El
151effb27eeSAndy Fiddaman.Sh INTERFACE STABILITY
152effb27eeSAndy FiddamanThe command line interface of
153effb27eeSAndy Fiddaman.Nm
154effb27eeSAndy Fiddamanis
155effb27eeSAndy Fiddaman.Sy Uncommitted .
156dd442252SAndy FiddamanThe output of
157dd442252SAndy Fiddaman.Nm
158dd442252SAndy Fiddamanis
159dd442252SAndy Fiddaman.Sy Not-An-Interface
160dd442252SAndy Fiddamanand may change at any time.
161effb27eeSAndy Fiddaman.Sh SEE ALSO
162effb27eeSAndy Fiddaman.Xr ctfdiff 1 ,
163effb27eeSAndy Fiddaman.Xr ctfdump 1 ,
164effb27eeSAndy Fiddaman.Xr ctf 4
165